@majkapp/plugin-kit 3.7.3 → 3.7.5

package/docs/CONVERSATIONS_API.md

@@ -0,0 +1,283 @@
+# Conversations API
+
+Access and manage MAJK conversations with filtering, searching, and message handling.
+
+## Quick Start
+
+```typescript
+handler: async (input, ctx) => {
+  // List recent conversations
+  const conversations = await ctx.majk.conversations.list({
+    status: 'active'
+  });
+
+  // Get specific conversation
+  const conv = await ctx.majk.conversations.get('conv-123');
+  if (conv) {
+    const messages = await conv.getMessages({ limit: 10 });
+    return { title: conv.title, messageCount: messages.length };
+  }
+
+  return { conversations: conversations.length };
+}
+```
+
+## API Reference
+
+### get(id)
+
+Get a conversation by ID.
+
+```typescript
+const conv = await ctx.majk.conversations.get('conv-123');
+// Returns: ConversationHandle | null
+```
+
+### list(filter?)
+
+List conversations with optional filters.
+
+```typescript
+const conversations = await ctx.majk.conversations.list({
+  status?: 'active' | 'completed' | 'failed' | 'cancelled',
+  agentId?: string,
+  projectId?: string,
+  teamMemberId?: string,
+  createdAfter?: Date,
+  createdBefore?: Date
+});
+// Returns: ConversationHandle[]
+```
+
+### exists(id)
+
+Check if a conversation exists.
+
+```typescript
+const exists = await ctx.majk.conversations.exists('conv-123');
+// Returns: boolean
+```
+
+### count(filter?)
+
+Count conversations matching a filter.
+
+```typescript
+const count = await ctx.majk.conversations.count({ status: 'active' });
+// Returns: number
+```
+
+### search(query)
+
+Search conversations by text.
+
+```typescript
+const results = await ctx.majk.conversations.search('authentication bug');
+// Returns: ConversationHandle[]
+```
+
+### channel()
+
+Get the event channel for conversations.
+
+```typescript
+const channel = ctx.majk.conversations.channel();
+```
+
+## ConversationHandle
+
+Handle returned from get/list operations.
+
+### Properties
+
+```typescript
+interface ConversationHandle {
+  readonly id: string;
+  readonly agentId: string;
+  readonly title: string;
+  readonly status: 'active' | 'completed' | 'failed' | 'cancelled';
+  readonly messageCount: number;
+  readonly lastMessageAt?: Date;
+  readonly workingDirectory?: string;
+  readonly projectId?: string;
+  readonly teamMemberId?: string;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly version: number;
+}
+```
+
+### Methods
+
+#### refresh()
+
+Refresh the handle with latest data.
+
+```typescript
+await conv.refresh();
+```
+
+#### getMessages(options?)
+
+Get conversation messages.
+
+```typescript
+const messages = await conv.getMessages({
+  limit?: number,
+  beforeSeq?: number,
+  afterSeq?: number
+});
+// Returns: Message[]
+```
+
+#### send(message)
+
+Send a message to the conversation.
+
+```typescript
+await conv.send('Please continue with the analysis');
+```
+
+#### getAgent()
+
+Get the agent associated with this conversation.
+
+```typescript
+const agent = await conv.getAgent();
+```
+
+#### onChange(handler)
+
+Subscribe to conversation changes.
+
+```typescript
+const unsubscribe = conv.onChange((updated) => {
+  console.log('Conversation updated:', updated.title);
+});
+
+// Later
+unsubscribe();
+```
+
+#### onDelete(handler)
+
+Subscribe to deletion events.
+
+```typescript
+const unsubscribe = conv.onDelete(() => {
+  console.log('Conversation was deleted');
+});
+```
+
+#### toEntity()
+
+Convert handle to plain entity object.
+
+```typescript
+const entity = conv.toEntity();
+// Returns: Conversation
+```
+
+## Message Type
+
+```typescript
+interface Message {
+  id: string;
+  conversationId: string;
+  role: 'user' | 'assistant' | 'tool' | 'system';
+  content: string;
+  seq: number;
+  createdAt: Date;
+  updatedAt: Date;
+  version: number;
+}
+```
+
+## Common Patterns
+
+### Filter Active Conversations
+
+```typescript
+const active = await ctx.majk.conversations.list({
+  status: 'active',
+  createdAfter: new Date(Date.now() - 24 * 60 * 60 * 1000) // Last 24 hours
+});
+
+for (const conv of active) {
+  ctx.logger.info(`Active: ${conv.title} (${conv.messageCount} messages)`);
+}
+```
+
+### Get Recent Messages
+
+```typescript
+const conv = await ctx.majk.conversations.get(conversationId);
+if (conv) {
+  // Get last 20 messages
+  const messages = await conv.getMessages({ limit: 20 });
+
+  // Get messages before a specific sequence
+  const older = await conv.getMessages({ beforeSeq: 50, limit: 10 });
+}
+```
+
+### Search and Analyze
+
+```typescript
+const results = await ctx.majk.conversations.search('error handling');
+
+for (const conv of results) {
+  const messages = await conv.getMessages();
+  const errorMessages = messages.filter(m =>
+    m.content.toLowerCase().includes('error')
+  );
+
+  ctx.logger.info(`${conv.title}: ${errorMessages.length} error-related messages`);
+}
+```
+
+### Monitor Conversation Changes
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  const conversations = await ctx.majk.conversations.list({ status: 'active' });
+
+  const unsubscribes = conversations.map(conv =>
+    conv.onChange((updated) => {
+      ctx.logger.info(`Conversation ${updated.id} updated`);
+    })
+  );
+
+  cleanup(() => {
+    unsubscribes.forEach(unsub => unsub());
+  });
+})
+```
+
+### Aggregate Statistics
+
+```typescript
+async function getConversationStats() {
+  const [active, completed, failed] = await Promise.all([
+    ctx.majk.conversations.count({ status: 'active' }),
+    ctx.majk.conversations.count({ status: 'completed' }),
+    ctx.majk.conversations.count({ status: 'failed' })
+  ]);
+
+  return { active, completed, failed, total: active + completed + failed };
+}
+```
+
+## Best Practices
+
+1. **Use filters** - Avoid listing all conversations when possible
+2. **Paginate messages** - Use limit/beforeSeq for large conversations
+3. **Cleanup subscriptions** - Always unsubscribe from onChange/onDelete
+4. **Refresh when needed** - Call refresh() before critical operations
+5. **Handle null** - get() may return null if conversation doesn't exist
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --context` - Full context API
+Run `npx @majkapp/plugin-kit --tasks` - Task management
+Run `npx @majkapp/plugin-kit --agents` - Agent configuration

package/docs/DELEGATION.md

@@ -0,0 +1,196 @@
+# Delegation API
+
+Multi-agent task delegation with witness-based verification. Delegate tasks to teammates and verify completion with automated checks.
+
+## Quick Start
+
+```typescript
+handler: async (input, ctx) => {
+  // List available teammates
+  const { teammates } = await ctx.majk.delegation.list_teammates();
+
+  // Delegate a task
+  const result = await ctx.majk.delegation.delegate_task({
+    teammate: 'code-reviewer',
+    task: 'Review the auth module for security issues',
+    witness: { bash: 'npm test' }
+  });
+
+  // Wait for completion
+  const status = await ctx.majk.delegation.await_task({
+    taskId: result.taskId
+  });
+
+  return { success: status.status === 'completed' };
+}
+```
+
+## API Reference
+
+### list_teammates()
+
+List all available teammates that can be delegated tasks to.
+
+```typescript
+const { teammates, count } = await ctx.majk.delegation.list_teammates();
+// teammates: Array<{ id, name, skills?, description? }>
+```
+
+### delegate_task(input)
+
+Delegate a task to a teammate asynchronously. Returns immediately with a task ID.
+
+```typescript
+const result = await ctx.majk.delegation.delegate_task({
+  teammate: string,       // Teammate name or ID
+  task: string,           // Task description
+  witness: Witness,       // Verification criteria
+  context?: Witness,      // Additional context
+  workingDirectory?: string
+});
+// Returns: { taskId, teammateId, teammateName, conversationId, status: 'running' }
+```
+
+### await_task(input)
+
+Wait for a task to complete. Blocks until finished or timeout.
+
+```typescript
+const status = await ctx.majk.delegation.await_task({
+  taskId: string,
+  timeoutMs?: number    // Default: no timeout
+});
+// Returns: DelegationTaskStatusOutput
+```
+
+### await_tasks(input)
+
+Wait for multiple tasks (fan-out/fan-in pattern).
+
+```typescript
+const results = await ctx.majk.delegation.await_tasks({
+  taskIds: string[],
+  timeoutMs?: number
+});
+// Returns: { results, summary: { total, completed, failed, blocked, stillRunning }, allCompleted, allSucceeded }
+```
+
+### check_task_status(input)
+
+Check current status of a delegated task.
+
+```typescript
+const status = await ctx.majk.delegation.check_task_status({
+  taskId: string,
+  messageCount?: number  // Include recent messages
+});
+```
+
+### check_witness(input)
+
+Run a witness verification immediately.
+
+```typescript
+const result = await ctx.majk.delegation.check_witness({
+  witness: Witness,
+  workingDirectory?: string
+});
+// Returns: { passed, evidence, strength, executionTimeMs }
+```
+
+### get_blockers(input?)
+
+List all currently blocked tasks.
+
+```typescript
+const { blockers, count } = await ctx.majk.delegation.get_blockers({
+  teammateId?: string,
+  assignedTo?: string
+});
+```
+
+### resolve_blocker(input)
+
+Resolve a blocker on a task.
+
+```typescript
+const result = await ctx.majk.delegation.resolve_blocker({
+  taskId: string,
+  action: 'update_task' | 'update_witness' | 'send_instruction' | 'unblock',
+  newTask?: string,
+  newWitness?: Witness,
+  instruction?: string,
+  resolution?: string
+});
+```
+
+## Witness Types
+
+Witnesses verify task completion:
+
+```typescript
+// Command execution
+{ bash: 'npm test' }
+{ bash: { command: 'npm test', exit_code: 0, stdout_contains: 'passed' } }
+
+// File checks
+{ file: { path: 'output.json', exists: true, contains: 'success' } }
+
+// HTTP checks
+{ http: { url: 'http://localhost:3000/health', status: 200 } }
+
+// AI verification
+{ llm: { prompt: 'Does this code handle errors properly?', file: 'src/handler.ts' } }
+
+// Visual verification
+{ vision: { image: 'screenshot.png', checklist: ['Has submit button', 'Shows form'] } }
+
+// JavaScript
+{ js: { code: 'return fs.existsSync("output.txt")' } }
+
+// Combine witnesses
+{ all: [{ bash: 'npm test' }, { file: { path: 'coverage.json', exists: true } }] }
+{ any: [{ bash: 'npm test' }, { bash: 'yarn test' }] }
+```
+
+## Fan-Out/Fan-In Pattern
+
+```typescript
+// Delegate to multiple teammates in parallel
+const tasks = await Promise.all([
+  ctx.majk.delegation.delegate_task({
+    teammate: 'backend-dev',
+    task: 'Implement the API endpoint',
+    witness: { bash: 'npm test -- --grep "api"' }
+  }),
+  ctx.majk.delegation.delegate_task({
+    teammate: 'frontend-dev',
+    task: 'Build the UI component',
+    witness: { bash: 'npm test -- --grep "ui"' }
+  })
+]);
+
+// Wait for all to complete
+const results = await ctx.majk.delegation.await_tasks({
+  taskIds: tasks.map(t => t.taskId),
+  timeoutMs: 300000
+});
+
+if (results.allSucceeded) {
+  ctx.logger.info('All tasks completed successfully');
+}
+```
+
+## Best Practices
+
+1. **Clear task descriptions** - Be specific about what needs to be done
+2. **Appropriate witnesses** - Choose verification that proves completion
+3. **Handle blockers** - Monitor and resolve blocked tasks
+4. **Set timeouts** - Prevent indefinite waits
+5. **Use fan-out for parallelism** - Delegate independent tasks simultaneously
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --batch` - Batch processing API
+Run `npx @majkapp/plugin-kit --tasks` - Task management API
+Run `npx @majkapp/plugin-kit --teammates` - Teammate configuration

package/docs/INDEX.md

@@ -633,8 +633,30 @@ onClick={() => {
 }}
 ```
 
+## Additional MAJK APIs
+
+The `ctx.majk` object provides access to many powerful APIs beyond the basics covered above:
+
+| API | Command | Description |
+|-----|---------|-------------|
+| **Delegation** | `--delegation` | Multi-agent task delegation with witness-based verification. Delegate tasks to teammates, fan-out/fan-in patterns, and automated completion checking. |
+| **Batch** | `--batch` | Batch processing for large datasets. Process files, lists, or glob patterns with parallelism, retry logic, and progress tracking. |
+| **Reports** | `--reports` | Knowledge management system with hierarchical reports, witness validation, views, and import/export capabilities. |
+| **Scripting** | `--scripting` | Execute JavaScript scripts that orchestrate tool calls. Includes dry-run mode, tracing, and script re-execution. |
+| **Tool Discovery** | `--tool-discovery` | Discover available service functions dynamically and invoke them. Build adaptive workflows based on available tools. |
+| **Skills** | `--skills` | Register and manage skills - instructions on how to accomplish tasks using tools. Supports runtime skills with setup/teardown. |
+| **Auth** | `--auth` | Core Cognito/MAJK authentication. Retrieve access tokens for calling MAJK backend services and AWS resources. |
+| **Secrets** | `--secrets` | Secure secret storage with scoping (global, project, integration). Store and retrieve API keys, tokens, and credentials. |
+| **Config** | `--config-api` | Access MAJK configuration using dot-notation paths. Read AWS, auth, Bedrock, and plugin settings. |
+| **Plugins** | `--plugins` | Plugin lifecycle management. Install, start, stop, reload plugins programmatically. Health checks and logging. |
+| **Tasks** | `--tasks` | Start and monitor asynchronous tasks. Send messages, track progress, and handle completion events. |
+| **Knowledge** | `--knowledge` | Knowledge trees for organizing information. Add nodes, search, and track references across conversations. |
+| **Agents** | `--agents` | Create, configure, test, and clone AI agents. Manage MCP servers and agent settings. |
+| **Conversations** | `--conversations` | Access and manage conversations. List, filter, search, get messages, and subscribe to changes. |
+
 ## Next Steps
 
+**Core Plugin Development:**
 Run `npx @majkapp/plugin-kit --functions` - Deep dive into function patterns
 Run `npx @majkapp/plugin-kit --screens` - Screen configuration details
 Run `npx @majkapp/plugin-kit --hooks` - Generated hooks reference
@@ -646,3 +668,19 @@ Run `npx @majkapp/plugin-kit --lifecycle` - onReady and cleanup
 Run `npx @majkapp/plugin-kit --testing` - Complete testing guide
 Run `npx @majkapp/plugin-kit --config` - vite.config.js and project setup
 Run `npx @majkapp/plugin-kit --full` - Complete reference
+
+**Additional APIs:**
+Run `npx @majkapp/plugin-kit --delegation` - Task delegation with witnesses
+Run `npx @majkapp/plugin-kit --batch` - Batch processing
+Run `npx @majkapp/plugin-kit --reports` - Knowledge management
+Run `npx @majkapp/plugin-kit --scripting` - Script execution
+Run `npx @majkapp/plugin-kit --tool-discovery` - Dynamic tool invocation
+Run `npx @majkapp/plugin-kit --skills` - Skill management
+Run `npx @majkapp/plugin-kit --auth` - Cognito authentication
+Run `npx @majkapp/plugin-kit --secrets` - Secret storage
+Run `npx @majkapp/plugin-kit --config-api` - Configuration access
+Run `npx @majkapp/plugin-kit --plugins` - Plugin management
+Run `npx @majkapp/plugin-kit --tasks` - Task monitoring
+Run `npx @majkapp/plugin-kit --knowledge` - Knowledge trees
+Run `npx @majkapp/plugin-kit --agents` - Agent configuration
+Run `npx @majkapp/plugin-kit --conversations` - Conversation access