Events Reference

Subscribe to SDK events using Pillar.on() or the on method from usePillar().

Subscribing to Events

examples/reference/events/subscribe-react.tsx

// React
const { on } = usePillar();

useEffect(() => {
  const unsubscribe = on('panel:open', () => {
    console.log('Panel opened');
  });
  return unsubscribe;
}, [on]);

examples/reference/events/subscribe-vanilla.js

// Vanilla JS
const unsubscribe = Pillar.on('panel:open', () => {
  console.log('Panel opened');
});

Lifecycle Events

Event	Payload	Description
`ready`	`void`	SDK initialized and ready
`error`	`{ message: string, code?: string }`	An error occurred

examples/reference/events/lifecycle-events.js

Pillar.on('ready', () => {
  console.log('Pillar SDK is ready');
});

Pillar.on('error', ({ message, code }) => {
  console.error(`Pillar error: ${message}`, code);
});

Panel Events

Event	Payload	Description
`panel:open`	`void`	Panel was opened
`panel:close`	`void`	Panel was closed

examples/reference/events/panel-events.js

Pillar.on('panel:open', () => {
  analytics.track('help_panel_opened');
});

Pillar.on('panel:close', () => {
  analytics.track('help_panel_closed');
});

Task Events

Event	Payload	Description
`task:execute`	`{ name: string, data: object }`	A task was executed
`task:complete`	`{ name: string, success: boolean }`	A task completed
`task:error`	`{ name: string, error: string }`	A task failed

examples/reference/events/task-events.js

Pillar.on('task:execute', ({ name, data }) => {
  analytics.track('action_executed', { action: name });
});

Pillar.on('task:complete', ({ name, success }) => {
  console.log(`Task ${name} completed:`, success);
});

Plan Events

Event	Payload	Description
`plan:start`	`ExecutionPlan`	A plan started executing
`plan:step:active`	`{ plan: ExecutionPlan, step: ExecutionStep }`	A step became active
`plan:step:complete`	`{ plan: ExecutionPlan, step: ExecutionStep, success: boolean }`	A step completed
`plan:step:skip`	`{ plan: ExecutionPlan, step: ExecutionStep }`	A step was skipped
`plan:complete`	`ExecutionPlan`	All steps finished
`plan:cancel`	`ExecutionPlan`	Plan was cancelled
`plan:error`	`{ plan: ExecutionPlan, error: string }`	Plan encountered an error

examples/reference/events/plan-events.js

Pillar.on('plan:start', (plan) => {
  console.log('Started plan:', plan.goal);
});

Pillar.on('plan:step:complete', ({ plan, step, success }) => {
  analytics.track('plan_step_complete', {
    planId: plan.id,
    stepIndex: step.index,
    success,
  });
});

Pillar.on('plan:complete', (plan) => {
  showConfetti();
  analytics.track('plan_complete', { planId: plan.id });
});

Theme Events

Event	Payload	Description
`theme:change`	`{ mode: string, colors?: object }`	Theme was updated

examples/reference/events/theme-events.js

Pillar.on('theme:change', ({ mode }) => {
  console.log('Theme changed to:', mode);
});

Chat Events

Event	Payload	Description
`chat:message:user`	`{ message: string }`	User sent a message
`chat:message:assistant`	`{ message: string }`	AI responded

examples/reference/events/chat-events.js

Pillar.on('chat:message:user', ({ message }) => {
  analytics.track('user_question', { question: message });
});

Type Definitions

ExecutionPlan

examples/reference/events/execution-plan.ts

interface ExecutionPlan {
  id: string;
  goal: string;
  status: 'awaiting_start' | 'executing' | 'awaiting_result' | 'completed' | 'cancelled' | 'failed';
  steps: ExecutionStep[];
  completed_steps: number;
  total_steps: number;
}

ExecutionStep

examples/reference/events/execution-step.ts

interface ExecutionStep {
  id: string;
  index: number;
  description: string;
  action_name: string;
  action_data: Record<string, unknown>;
  status: 'pending' | 'active' | 'completed' | 'skipped' | 'failed';
  auto_run: boolean;
  auto_complete: boolean;
  requires_user_confirmation: boolean;
}

Best Practices

Clean Up Subscriptions

Always unsubscribe when the component unmounts:

examples/reference/events/cleanup-subscriptions.tsx

useEffect(() => {
  const unsubscribers = [
    on('panel:open', handleOpen),
    on('plan:complete', handlePlanComplete),
  ];

  return () => unsubscribers.forEach(unsub => unsub());
}, [on]);

Use for Analytics

Events are perfect for tracking user behavior:

examples/reference/events/analytics-events.js

Pillar.on('task:execute', ({ name }) => {
  analytics.track('pillar_action', { action: name });
});

Pillar.on('plan:complete', ({ id, goal }) => {
  analytics.track('pillar_plan_complete', { planId: id, goal });
});

Search documentation