Action Delegation

Overview

The Butler's action delegation system routes user actions (e.g., "log expense", "add to list") to the right Butler. The Butler resolves intents and hands off to the appropriate Butler so one tap or command does the right thing. Your Butler can register actions it can handle and respond to intent queries.

Register Actions

Register actions that your Butler can handle. These actions can be triggered from voice commands, quick actions, or other Butlers.

Action Registration

// Register actions your Butler can handle
await window.lifeButler.registerActions([
  {
    id: 'log-expense',
    name: 'Log Expense',
    description: 'Log a new expense transaction',
    keywords: ['expense', 'spend', 'transaction', 'payment'],
    handler: async (params) => {
      // Handle the action
      const expense = await createExpense(params);
      return { success: true, expenseId: expense.id };
    }
  },
  {
    id: 'view-expenses',
    name: 'View Expenses',
    description: 'View expense history',
    keywords: ['expenses', 'spending', 'transactions'],
    handler: async (params) => {
      navigateToExpenses(params);
      return { success: true };
    }
  }
]);

Intent Resolution

When The Butler receives a user command, it queries all Butlers to determine which one can handle it. Your Butler responds to intent queries with a likelihood score.

Handle Intent Queries

// Respond to intent queries
window.lifeButler.onIntentQuery(async (intent) => {
  const { action, params, context } = intent;
  
  // Determine if your Butler can handle this intent
  const canHandle = canHandleIntent(action, params);
  
  if (canHandle) {
    return {
      butlerId: 'my-butler',
      actionId: 'log-expense',
      likelihood: 0.9,
      handler: async () => {
        return await handleLogExpense(params);
      }
    };
  }
  
  return null; // Don't handle if not applicable
});

function canHandleIntent(action, params) {
  // Check if action matches your Butler's capabilities
  if (action === 'log-expense' || action === 'add-expense') {
    return true;
  }
  
  // Check keywords
  const keywords = ['expense', 'spend', 'transaction'];
  if (keywords.some(kw => action.includes(kw))) {
    return true;
  }
  
  return false;
}

Quick Actions

Register quick actions that appear in The Butler's quick action menu. These can be presented as full-screen apps or lightweight decision/input sheets.

Register Quick Actions

// Register quick actions
await window.lifeButler.registerQuickActions([
  {
    id: 'quick-log-expense',
    icon: '💰',
    label: 'Log Expense',
    type: 'input', // 'fullscreen' | 'decision' | 'input'
    handler: async (input) => {
      // Handle quick action
      const expense = await createExpense(input);
      return { success: true };
    },
    inputConfig: {
      fields: [
        { name: 'amount', type: 'number', label: 'Amount' },
        { name: 'category', type: 'text', label: 'Category' }
      ]
    }
  },
  {
    id: 'quick-view-expenses',
    icon: '📊',
    label: 'View Expenses',
    type: 'fullscreen',
    handler: async () => {
      navigateToExpenses();
      return { success: true };
    }
  }
]);

Voice Commands

Actions can be triggered via voice commands. The Butler processes voice input and routes it to the appropriate Butler.

Voice Command Handling

Voice commands are automatically routed through the intent resolution system. Ensure your actions have appropriate keywords for voice recognition.

// Voice commands are handled automatically through intent resolution
// Example: User says "log an expense of 25 dollars"
// The Butler processes this and calls your action handler:

{
  action: 'log-expense',
  params: {
    amount: 25,
    currency: 'USD'
  }
}

// Your handler receives this and processes it
async function handleLogExpense(params) {
  const expense = await createExpense({
    amount: params.amount,
    currency: params.currency || 'USD',
    date: new Date()
  });
  return { success: true, expenseId: expense.id };
}

Requirements

• Register actions: Register all actions your Butler can handle with appropriate keywords and handlers.
• Respond to intents: Implement intent query handler to respond when The Butler queries for action handlers.
• Provide accurate likelihood: Return accurate likelihood scores so The Butler can route actions to the best Butler.
• Handle errors gracefully: Return error information if action handling fails, so The Butler can try alternative Butlers or show error messages.
• Support quick actions: Register quick actions for common operations to improve user experience.