Deep Dive: Kontask Action API Architecture

💡 The Key Insight

You're right - prompt injection is the current workaround, not the end goal. The "What's Next" buttons just stuff text into the input. But kontask cards could be mini-agents with direct access to the full capability stack.

📊 Capability Spectrum

🤔 Design Questions

🎬 Concrete Examples by Level

// FileTree component click handler
window.handleFileSelect = async (node) => {
  // Direct API call - no Claude needed
  await kontask.api.updateContext({
    selectedFile: node.path,
    previewContent: await kontask.api.readFile(node.path, { lines: 50 })
  });
  // Kontask card updates in-place with file preview
};

// Run grep from within kontask card
window.handleSearch = async (query) => {
  const results = await kontask.tools.grep({
    pattern: query,
    path: '/konnectvol/konui',
    type: 'ts'
  });
  // Results render in kontask card - no new turn
  kontask.render('searchResults', results);
};

// Kontask spawns mini-agent for complex task
window.handleImplement = async (feature) => {
  // Spawn scoped agent with limited tools
  const agent = await kontask.spawnAgent({
    prompt: `Implement ${feature.name}`,
    tools: ['Read', 'Edit', 'Grep'],  // No Bash!
    scope: feature.files,
    budget: { maxTurns: 5, maxTokens: 50000 }
  });
  
  // Stream progress into kontask card
  agent.on('progress', (update) => kontask.appendProgress(update));
  agent.on('complete', (result) => kontask.showResult(result));
};

🏗️ Architecture Vision

┌─────────────────────────────────────────────────────────────┐
│                    KONTASK CARD                            │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Interactive Component (FileTree, Chart, etc.)       │   │
│  │                                                      │   │
│  │   onClick ─────────────────────────────────────┐    │   │
│  └──────────────────────────────────────────────────────┘   │
│                           │                                  │
│  ┌────────────────────────▼─────────────────────────────┐   │
│  │           kontask.api (Action SDK)                   │   │
│  │  ┌─────────┬──────────┬──────────┬──────────────┐   │   │
│  │  │ L1      │ L2       │ L3       │ L4          │   │   │
│  │  │ submit  │ konui    │ tools    │ spawnAgent   │   │   │
│  │  │ Prompt  │ API      │ Execute  │              │   │   │
│  │  └────┬────┴────┬─────┴────┬─────┴──────┬───────┘   │   │
│  └───────│─────────│──────────│────────────│───────────┘   │
└──────────│─────────│──────────│────────────│───────────────┘
           │         │          │            │
           ▼         ▼          ▼            ▼
      ┌─────────┐ ┌──────┐ ┌─────────┐ ┌───────────┐
      │ Console │ │Konui │ │Konsole  │ │ gvShell   │
      │ Input   │ │Router│ │ Tools   │ │ Agent     │
      └─────────┘ └──────┘ └─────────┘ └───────────┘

📦 The kontask.api SDK

Auto-injected into every kontask card. Provides graduated access:

// Always available
kontask.id                    // This kontask's ID
kontask.sessionId             // Parent session ID
kontask.context               // Read-only kontask context

// L1: Prompt submission
kontask.submit(prompt)        // Auto-submit to console
kontask.submitWithContext(prompt, data)  // Include structured data

// L2: Konui direct actions
kontask.navigate(path)        // Navigate dashboard
kontask.approve()             // Approve this kontask
kontask.reject(reason)        // Reject with reason
kontask.updateContext(data)   // Update this kontask's context
kontask.createKontask(spec)   // Create child kontask

// L3: Tool execution (requires capability)
kontask.tools.read(path)      // Read file
kontask.tools.grep(opts)      // Search code
kontask.tools.glob(pattern)   // Find files
kontask.tools.bash(cmd)       // Run command (if allowed)

// L4: Agent spawning (requires capability)
kontask.spawnAgent(spec)      // Launch scoped agent
kontask.joinFlow(flowId)      // Join existing flow

// UI helpers
kontask.render(id, html)      // Update element in card
kontask.appendProgress(msg)   // Add progress line
kontask.toast(msg, type)      // Show notification
kontask.loading(show)         // Toggle loading state

🛡️ Capability Declaration

Kontasks declare what they need upfront. Konui validates and enforces.

// When creating kontask, declare capabilities
await konui_create_task({
  type: "general",
  title: "Code Explorer",
  context: {
    capabilities: {
      level: 3,  // Max level allowed
      tools: ["Read", "Grep", "Glob"],  // Allowed tools
      scope: "/konnectvol/konui",  // Path restriction
      budget: { maxCalls: 10 }  // Rate limiting
    },
    output: "...interactive file browser..."
  }
});

🎯 Summary: What Are We Building?

Not just an action API - a graduated capability system that lets kontask cards range from simple buttons (L0) to embedded agents (L4), with proper security at each level.

This is the bridge between "kontasks as static cards" and "kontasks as mini-agents" that can do real work without spawning full Claude turns.