@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-4

package/docs/proposals/action-composition.md

@@ -1,490 +0,0 @@
-# Action Composition Pattern
-
-> **Status**: APPROVED - Ready for implementation  
-> **Date**: 2026-01-19  
-> **Branch**: `feat/mcp-tool-restructure`
-
-## Summary
-
-Replace flag-based parameters with composable action arrays for multi-step operations.
-
-## Problem: Flag-Based Parameters Encode Operations in Names
-
-```typescript
-// Current: semantics encoded in parameter names
-persona(
-    method="create",
-    from="source-id",
-    name="Demo Clone",
-    include_data=true,      // ← "include" + "data" = copy operation
-    sanitize=true,          // ← operation encoded in name
-    sanitize_examples=[...] // ← coupled to sanitize flag
-)   
-```
-
-**Issues:**
-
-| Problem | Impact |
-|---------|--------|
-| **Name = Operation** | `include_data` implies "copy data" - hidden in name |
-| **Coupled parameters** | `sanitize_examples` only valid when `sanitize=true` |
-| **Schema bloat** | Every capability = new parameter |
-| **Combinatorial explosion** | `include_data` × `sanitize` × `generate` × `link` |
-| **Hidden order** | copy then sanitize? sanitize then copy? |
-| **Extensibility** | New capability = new flag = schema change |
-
-## Solution: Action Composition
-
-```typescript
-// Proposed: operations as composable actions
-persona(
-    method="create",
-    from="source-id", 
-    name="Demo Clone",
-    actions=[
-        {tool:"data", args:{method:"copy", from:"$source"}},
-        {tool:"data", args:{method:"sanitize", examples:["Acme Corp"]}},
-        {tool:"snapshot", args:{message:"Clone ready"}},
-    ]
-)
-```
-
-**Benefits:**
-
-| Benefit | Description |
-|---------|-------------|
-| **Explicit operations** | `{tool:"data", args:{method:"copy"}}` not `include_data:true` |
-| **Composable** | Mix/match/reorder any actions |
-| **Self-contained** | Each action has its own params |
-| **Order explicit** | Array order = execution order |
-| **Schema stable** | New actions don't change persona schema |
-| **Reuses tools** | Same schema as direct tool calls |
-
-## Design
-
-### Actions Property
-
-```typescript
-persona.inputSchema.properties.actions = {
-  type: "array",
-  description: "Post-operation actions to execute in sequence",
-  items: {
-    oneOf: [
-      // Object form: explicit tool + args
-      {
-        type: "object",
-        properties: {
-          tool: { 
-            type: "string", 
-            enum: ["data", "snapshot", "validate"],
-            description: "Tool to invoke" 
-          },
-          args: { 
-            type: "object",
-            description: "Arguments (same schema as direct tool call)" 
-          }
-        },
-        required: ["tool", "args"]
-      },
-      // String form: alias reference
-      {
-        type: "string",
-        description: "Alias name (e.g., 'standard-demo-setup')"
-      }
-    ]
-  }
-}
-```
-
-### Context Variables
-
-Actions can reference context from the base operation:
-
-| Variable | Description |
-|----------|-------------|
-| `$source` | Source persona ID (from `from` parameter) |
-| `$target` | Created/cloned persona ID (result of base op) |
-| `$env` | Current environment |
-
-```typescript
-// $source and $target auto-populated
-persona(
-  method="create",
-  from="template-123",       // $source = "template-123"
-  name="New Persona",
-  actions=[
-    // $target = ID of newly created persona
-    {tool:"data", args:{method:"copy", from:"$source"}},
-    {tool:"data", args:{method:"sanitize"}},
-    {tool:"snapshot", args:{message:"Created from $source"}},
-  ]
-)
-```
-
-### Supported Action Tools
-
-| Tool | Description | Example |
-|------|-------------|---------|
-| `data` | Data operations (copy, upload, sanitize) | `{tool:"data", args:{method:"copy", from:"src"}}` |
-| `snapshot` | Create version snapshot | `{tool:"snapshot", args:{message:"..."}}` |
-| `validate` | Run validation checks | `{tool:"validate", args:{checks:["workflow","config"]}}` |
-
-### Aliases
-
-Common patterns can be defined as aliases:
-
-```typescript
-// Built-in aliases
-const ACTION_ALIASES: Record<string, ActionSpec[]> = {
-  "copy-and-sanitize": [
-    {tool:"data", args:{method:"copy", from:"$source"}},
-    {tool:"data", args:{method:"sanitize"}},
-  ],
-  "standard-demo-setup": [
-    {tool:"data", args:{method:"copy", from:"$source"}},
-    {tool:"data", args:{method:"sanitize"}},
-    {tool:"snapshot", args:{message:"Demo setup complete"}},
-  ],
-};
-
-// Usage
-persona(
-  method="create",
-  from="prod-persona",
-  name="Demo Version",
-  actions=["copy-and-sanitize"]  // Expands to 2 actions
-)
-
-// Mixed usage
-persona(
-  method="create",
-  from="prod-persona",
-  name="Demo Version",
-  actions=[
-    "copy-and-sanitize",  // alias
-    {tool:"snapshot", args:{message:"Custom message"}},  // explicit
-  ]
-)
-```
-
-## Execution Model
-
-```
-persona(method="create", from="src", name="New", actions=[...])
-                │
-                ▼
-┌─────────────────────────────────────────┐
-│  1. Execute base operation (create)     │
-│     - Creates new persona "New"         │
-│     - Returns: { id: "new-123", ... }   │
-│     - Sets context: $target="new-123"   │
-└────────────────┬────────────────────────┘
-                 │
-                 ▼
-┌─────────────────────────────────────────┐
-│  2. Build execution context             │
-│     $source = "src"                     │
-│     $target = "new-123"                 │
-│     $env = "demo"                       │
-└────────────────┬────────────────────────┘
-                 │
-                 ▼
-┌─────────────────────────────────────────┐
-│  3. Expand aliases                      │
-│     "standard-demo-setup" → [           │
-│       {tool:"data", args:{...}},        │
-│       {tool:"data", args:{...}},        │
-│       {tool:"snapshot", args:{...}},    │
-│     ]                                   │
-└────────────────┬────────────────────────┘
-                 │
-                 ▼
-┌─────────────────────────────────────────┐
-│  4. Execute actions in sequence         │
-│     - Substitute context vars           │
-│     - Execute each action               │
-│     - Collect results                   │
-│     - Stop on error (unless continue)   │
-└────────────────┬────────────────────────┘
-                 │
-                 ▼
-┌─────────────────────────────────────────┐
-│  5. Return composite result             │
-│     {                                   │
-│       persona: { id: "new-123", ... },  │
-│       actions: [                        │
-│         { tool: "data", status: "ok" }, │
-│         { tool: "snapshot", ... },      │
-│       ]                                 │
-│     }                                   │
-└─────────────────────────────────────────┘
-```
-
-## Schema Changes
-
-### Before (Flag-Based)
-
-```typescript
-persona.inputSchema.properties = {
-  // ... other props ...
-  include_data: { type: "boolean" },
-  sanitize: { type: "boolean" },
-  sanitize_examples: { type: "array", items: { type: "string" } },
-  create_snapshot: { type: "boolean" },
-  snapshot_message: { type: "string" },
-  // Every new capability = new props
-}
-```
-
-### After (Action-Based)
-
-```typescript
-persona.inputSchema.properties = {
-  // ... other props ...
-  actions: {
-    type: "array",
-    description: "Post-operation actions to execute in sequence",
-    items: {
-      oneOf: [
-        {
-          type: "object",
-          properties: {
-            tool: { type: "string", enum: ["data", "snapshot", "validate"] },
-            args: { type: "object" }
-          },
-          required: ["tool", "args"]
-        },
-        { type: "string" }  // alias reference
-      ]
-    }
-  }
-}
-// Schema is stable - new actions don't require changes
-```
-
-## Implementation
-
-### 1. Action Executor Module
-
-```typescript
-// src/mcp/handlers/action-executor.ts
-
-interface ActionContext {
-  source?: string;      // from parameter
-  target?: string;      // result of base operation
-  env?: string;
-}
-
-interface ActionSpec {
-  tool: "data" | "snapshot" | "validate";
-  args: Record<string, unknown>;
-}
-
-interface ActionResult {
-  tool: string;
-  status: "success" | "error";
-  result?: unknown;
-  error?: string;
-}
-
-/**
- * Execute a sequence of actions with context substitution
- */
-export async function executeActions(
-  actions: (ActionSpec | string)[],
-  context: ActionContext,
-  client: EmaClient,
-): Promise<ActionResult[]> {
-  const results: ActionResult[] = [];
-  const expanded = expandAliases(actions);
-  
-  for (const action of expanded) {
-    const substituted = substituteContext(action, context);
-    try {
-      const result = await executeAction(substituted, context, client);
-      results.push({ tool: action.tool, status: "success", result });
-    } catch (error) {
-      results.push({ tool: action.tool, status: "error", error: String(error) });
-      break; // Stop on error
-    }
-  }
-  
-  return results;
-}
-
-/**
- * Substitute context variables in action args
- */
-function substituteContext(action: ActionSpec, context: ActionContext): ActionSpec {
-  const args = JSON.parse(JSON.stringify(action.args));
-  
-  function substitute(obj: Record<string, unknown>) {
-    for (const [key, value] of Object.entries(obj)) {
-      if (typeof value === "string") {
-        obj[key] = value
-          .replace(/\$source/g, context.source ?? "")
-          .replace(/\$target/g, context.target ?? "")
-          .replace(/\$env/g, context.env ?? "");
-      } else if (typeof value === "object" && value !== null) {
-        substitute(value as Record<string, unknown>);
-      }
-    }
-  }
-  
-  substitute(args);
-  return { tool: action.tool, args };
-}
-```
-
-### 2. Handler Integration
-
-```typescript
-// In handlePersona - after base operation
-
-// If actions provided, execute them
-if (Array.isArray(args.actions) && args.actions.length > 0) {
-  const context: ActionContext = {
-    source: args.from as string,
-    target: baseResult.id,
-    env: args.env as string,
-  };
-  
-  const actionResults = await executeActions(args.actions, context, client);
-  
-  return {
-    ...baseResult,
-    actions: actionResults,
-  };
-}
-```
-
-## Examples
-
-### Clone with Data Copy and Sanitization
-
-```typescript
-// Old way (flags)
-persona(
-  method="create",
-  from="prod-persona",
-  name="Demo Copy",
-  include_data=true,
-  sanitize=true,
-  sanitize_examples=["Acme Corp", "john@acme.com"]
-)
-
-// New way (actions)
-persona(
-  method="create",
-  from="prod-persona",
-  name="Demo Copy",
-  actions=[
-    {tool:"data", args:{method:"copy", from:"$source"}},
-    {tool:"data", args:{method:"sanitize", examples:["Acme Corp", "john@acme.com"]}},
-  ]
-)
-```
-
-### Clone with LLM-Generated Content
-
-```typescript
-persona(
-  method="create",
-  from="template-dashboard",
-  name="Test Dashboard",
-  actions=[
-    // LLM generates content, provides via upload
-    {tool:"data", args:{
-      method:"upload",
-      content:[
-        {document:{text:"Contract 1..."}, title:"Contract A", value:50000},
-        {document:{text:"Contract 2..."}, title:"Contract B", value:75000},
-      ]
-    }},
-    {tool:"snapshot", args:{message:"Initial test data loaded"}},
-  ]
-)
-```
-
-### Using Aliases
-
-```typescript
-// Simple alias
-persona(
-  method="create",
-  from="prod-persona",
-  name="Demo",
-  actions=["standard-demo-setup"]
-)
-
-// Alias + custom action
-persona(
-  method="create",
-  from="prod-persona",
-  name="Demo",
-  actions=[
-    "copy-and-sanitize",
-    {tool:"validate", args:{checks:["workflow"]}},
-    {tool:"snapshot", args:{message:"Validated and ready"}},
-  ]
-)
-```
-
-## Migration
-
-| Old (Flag-Based) | New (Action-Based) |
-|------------------|-------------------|
-| `include_data=true` | `actions=[{tool:"data", args:{method:"copy", from:"$source"}}]` |
-| `sanitize=true` | `actions=[{tool:"data", args:{method:"sanitize"}}]` |
-| `sanitize_examples=[...]` | `args:{..., examples:[...]}` in sanitize action |
-| Combined flags | Actions array with both operations |
-
-**Backward Compatibility:**
-
-Phase 1: Support both flags and actions (flags converted to actions internally)
-Phase 2: Deprecation warnings for flag usage
-Phase 3: Remove flag parameters
-
-## Comparison: Adding New Capability
-
-**Scenario:** Add "link data instead of copy" capability
-
-### Flag-Based
-
-```typescript
-// Schema change required - new parameter
-inputSchema.properties.link_data = { type: "boolean" };
-
-// Or worse, mode enum expansion
-inputSchema.properties.data_mode = { 
-  enum: ["copy", "link", "copy_sanitized", ...] 
-};
-```
-
-### Action-Based
-
-```typescript
-// No schema change - use existing data action with option
-actions=[
-  {tool:"data", args:{method:"copy", from:"$source", link:true}}
-]
-```
-
-## Open Questions
-
-1. **Error handling**: Stop on first error, or continue and report all?
-   - **Decision**: Stop on error by default, add `continue_on_error: true` option
-
-2. **Parallel execution**: Should independent actions run in parallel?
-   - **Decision**: Sequential by default, add `parallel: true` option for future
-
-3. **Alias management**: Where to define custom aliases?
-   - **Decision**: Built-in aliases only for v1, custom alias config for future
-
-## Approval
-
-- [x] Design reviewed
-- [x] Architecture analyzed
-- [ ] Implementation started
-- [ ] Tests written
-- [ ] Documentation updated