> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Sidekick tool events

> Browser event contract for successful Mage tool calls from AI Sidekick

export const ProOnly = ({button = 'Get started for free', description = 'Try our fully managed solution to access this advanced feature.', source = 'documentation', title = 'Only in Mage Pro.'}) => <div className="block my-4 px-5 py-4 overflow-hidden rounded-xl flex gap-3 border border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10">
    <div style={{
  display: 'flex',
  alignItems: 'center',
  width: '100%'
}}>
      <div className="text-sm prose min-w-0 text-emerald-900 dark:text-emerald-200" style={{
  flex: 1
}}>
        <span className="font-semibold">{title}</span>
        <p className="normal">{description}</p>
      </div>

      <div> </div>

      <div style={{
  height: 32,
  position: 'relative'
}}>
        <a target="_blank" rel="noopener noreferrer" className="group px-4 py-1.5 relative inline-flex items-center text-sm font-medium rounded-full" href={`https://cloud.mage.ai/sign-up?source=${source}`}>
          <span className="absolute inset-0 bg-primary-dark dark:bg-primary-light/10 border-primary-light/30 rounded-full dark:border group-hover:opacity-[0.9] dark:group-hover:border-primary-light/60">
          </span>

          <div className="mr-0.5 space-x-2.5 flex items-center">
            <span className="z-10 text-white dark:text-primary-light">
              {button}
            </span>

            <svg width="3" height="24" viewBox="0 -9 3 24" className="h-5 rotate-0 overflow-visible text-white/90 dark:text-primary-light">
              <path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"></path>
            </svg>
          </div>
        </a>
      </div>
    </div>
  </div>;

<ProOnly source="ai-sidekick-tool-events" />

# AI Sidekick Tool Events

AI Sidekick emits browser events after successful Mage tool calls so open Mage Pro surfaces can update themselves without a page refresh.

This event path is for the Codex-backed Sidekick runtime. It does not use the legacy `AIProvider.createBlock`, `AIProvider.deleteBlock`, or `AIProvider.fetchPipeline` action bridge.

## Events

Every successful Mage tool call emits one tool-specific browser event:

```ts theme={"system"}
mage:<normalized_tool_name>
```

For example:

```ts theme={"system"}
mage:block_create
mage:block_delete
mage:pipeline_update
```

Tool names are normalized by removing the `mage:` prefix, lowercasing, replacing separators with `_`, and trimming leading or trailing separators.

## Event Detail

Each event uses this detail object:

```ts theme={"system"}
type SidekickToolSuccessEventDetail = {
  agentUuid?: string;
  artifact?: any;
  dedupeKey: string;
  eventName: string;
  item?: any;
  metadata?: Record<string, any>;
  normalizedToolName: string;
  operation?: "create" | "update" | "delete" | "read" | "execute" | string;
  request?: any;
  resource?: string;
  response: any;
  result?: any;
  server?: string;
  sessionUuid?: string;
  sourceEvent: {
    agent_uuid?: string;
    created_at?: string;
    event_type?: string;
    sequence?: number;
    session_uuid?: string;
    turn_uuid?: string;
    uuid?: string;
  };
  status: "success";
  toolEventName: string;
  toolName: string;
  turnUuid?: string;
};
```

The `request` field contains structured tool arguments when Sidekick has them. The `response` field contains the successful structured tool response after sensitive keys such as tokens, cookies, passwords, authorization headers, and prompts are redacted.

## Pipeline Editor Updates

The pipeline editor subscribes to block and pipeline mutation events:

* `block_create`
* `blocks_create`
* `block_delete`
* `blocks_delete`
* `block_update`
* `block_code_update`
* `blocks_update`
* `pipeline_update`
* `pipelines_update`

If the event targets a different pipeline, the editor ignores it. If the event includes a full pipeline payload, the editor applies that payload with callbacks enabled so the notebook, dependency graph, Sidekick tree, and code block state update together. If the event does not include a full pipeline payload, the editor refetches the current pipeline with callbacks enabled.

Delete events clear stale selected-block state and cached output state for deleted blocks. Create events scroll to the created block after the editor state refreshes.

## Non-Emission Cases

Sidekick does not emit success events for failed, cancelled, stale, optimistic-only, heartbeat, user-message, assistant text-only, or duplicate replay events.