@ellie-ai/action-tree-plugin

Action tree plugin for the Ellie runtime. Stores all dispatched actions in Redux state as a tree structure, allowing you to query and render them however you want.

Install

bun add @ellie-ai/action-tree-plugin

Quick start

import { createRuntime } from "@ellie-ai/runtime";
import { agentPlugin } from "@ellie-ai/agent-plugin";
import {
  actionTreePlugin,
  selectActionTree,
  renderTree,
} from "@ellie-ai/action-tree-plugin";

const agent = agentPlugin({ model });
const actionTree = actionTreePlugin();

const runtime = createRuntime({
  plugins: [actionTree, agent],
});

// Subscribe and render when you want
runtime.subscribe(() => {
  const tree = selectActionTree(runtime.getState());
  console.log(renderTree(tree));
});

Filtering actions with tap

Use the tap hook to filter out actions before they're stored:

import { actionTreePlugin, isStreamingDelta } from "@ellie-ai/action-tree-plugin";

const actionTree = actionTreePlugin({
  tap: (action) => {
    // Skip streaming deltas
    if (isStreamingDelta(action)) return null;
    return action;
  },
});

Accessing state

The plugin stores actions in state under the actionTree key:

const state = runtime.getState();
// state.actionTree.actions - Record of all stored actions
// state.actionTree.roots - Array of root action IDs

Use selectors to work with the tree:

import {
  selectActionTree,
  selectActions,
  selectRootIds,
} from "@ellie-ai/action-tree-plugin";

// Get tree structure for rendering
const tree = selectActionTree(state);

// Get raw actions map
const actions = selectActions(state);

// Get root action IDs
const roots = selectRootIds(state);

Custom rendering

The renderTree utility produces a formatted string, but you can render however you want:

import { selectActionTree } from "@ellie-ai/action-tree-plugin";

const tree = selectActionTree(runtime.getState());

// Custom rendering
function customRender(nodes, depth = 0) {
  for (const node of nodes) {
    console.log("  ".repeat(depth) + node.type);
    customRender(node.children, depth + 1);
  }
}

customRender(tree);

API

actionTreePlugin(options?)

Creates the plugin. Options:

• tap?: (action) => action | null - Filter/transform actions before storing

Selectors

• selectActionTree(state) - Returns tree structure (TreeNode[])
• selectActionTreeState(state) - Returns raw state
• selectActions(state) - Returns actions record
• selectRootIds(state) - Returns root action IDs

renderTree(tree, options?)

Renders tree to string. Options:

• ignoreActions?: string[] - Action types to skip in rendering

Utilities

• isStreamingDelta(action) - Check if action is a streaming delta
• isStreamingAction(action) - Check if action is streaming-related
• isTerminalExecution(action) - Check if action ends execution
• getActionId(action) - Extract action ID from metadata
• getParentActionId(action) - Extract parent action ID
• getExecutionId(action) - Extract execution ID