Your First Real Extension

mkdir tasks-mini && cd tasks-mini
python3.12 -m venv .venv && source .venv/bin/activate
pip install imperal-sdk

from dataclasses import dataclass, field
from datetime import datetime
from uuid import uuid4

@dataclass
class Task:
    id: str = field(default_factory=lambda: str(uuid4()))
    title: str = ""
    due_at: str | None = None
    done: bool = False
    created_at: str = field(default_factory=lambda: datetime.utcnow().isoformat())

# In-memory store keyed by user_id (multi-tenant safety baked in)
_TASKS: dict[str, list[Task]] = {}

def get_tasks(user_id: str) -> list[Task]:
    return _TASKS.setdefault(user_id, [])

def add_task(user_id: str, task: Task) -> Task:
    get_tasks(user_id).append(task)
    return task

def clear_done(user_id: str) -> int:
    tasks = get_tasks(user_id)
    before = len(tasks)
    _TASKS[user_id] = [t for t in tasks if not t.done]
    return before - len(_TASKS[user_id])

from imperal_sdk import Extension, ChatExtension, ActionResult
from pydantic import BaseModel, Field
from .state import Task, get_tasks, add_task, clear_done

# ─────────── parameter models ───────────

class CreateTaskParams(BaseModel):
    title: str = Field(description="The task — what needs to be done")
    due_at: str | None = Field(
        None,
        description="Optional ISO datetime when the task is due (e.g. '2026-06-15T09:00:00')",
    )

class ListTasksParams(BaseModel):
    only_pending: bool = Field(True, description="Hide completed tasks if True")

# ─────────── extension definition ───────────

ext = Extension(
    "tasks-mini",
    version="1.0.0",
    display_name="Tasks (Mini)",
    description="A tiny task manager Webbee can drive in plain language to add, list, and clear tasks.",
    icon="icon.svg",
    actions_explicit=True,
    capabilities=["tasks:read", "tasks:write", "tasks:delete"],
)

chat = ChatExtension(
    ext,
    tool_name="tasks_mini",
    description="Tasks (Mini) — a small to-do list managed via chat.",
)

# ─────────── handlers ───────────

@chat.function(
    "create_task",
    action_type="write",
    event="task_created",
    effects=["create:task"],
    description="Add a task to the user's pending list.",
)
async def create_task(ctx, params: CreateTaskParams) -> ActionResult:
    task = Task(title=params.title, due_at=params.due_at)
    add_task(ctx.user.imperal_id, task)
    return ActionResult.success(
        data={"task_id": task.id, "title": task.title},
        summary=f"Added: {task.title}",
    )

@chat.function(
    "list_tasks",
    action_type="read",
    description="List the user's tasks (optionally only the pending ones).",
)
async def list_tasks(ctx, params: ListTasksParams) -> ActionResult:
    tasks = get_tasks(ctx.user.imperal_id)
    if params.only_pending:
        tasks = [t for t in tasks if not t.done]
    return ActionResult.success(
        data={
            "tasks": [
                {"id": t.id, "title": t.title, "due_at": t.due_at, "done": t.done}
                for t in tasks
            ],
            "count": len(tasks),
        },
        summary=f"{len(tasks)} task(s)",
    )

class ClearDoneParams(BaseModel):
    confirm: bool = Field(False, description="Set true to actually clear (safety gate)")

@chat.function(
    "clear_done_tasks",
    action_type="destructive",
    event="tasks_cleared",
    effects=["delete:task"],
    description="Permanently remove all completed tasks. Destructive — confirmation required.",
)
async def clear_done_tasks(ctx, params: ClearDoneParams) -> ActionResult:
    count = clear_done(ctx.user.imperal_id)
    return ActionResult.success(
        data={"cleared": count},
        summary=f"Cleared {count} completed task(s).",
    )

from imperal_sdk import ui
from .app import ext
from .state import get_tasks

@ext.panel("sidebar", slot="left", title="My Tasks", icon="📋")
async def tasks_sidebar(ctx, **kwargs):
    tasks = get_tasks(ctx.user.imperal_id)
    pending = [t for t in tasks if not t.done]
    return ui.Stack(children=[
        ui.Header(f"{len(pending)} pending", level=3),
        ui.List(items=[
            ui.ListItem(id=t.id, title=t.title, subtitle=t.due_at or "")
            for t in pending[:10]
        ]),
    ], gap=2)

from .panels import tasks_sidebar  # noqa: F401  — registers the panel

imperal build

imperal test

import pytest
from imperal_sdk.testing import MockContext
from app import create_task, list_tasks, CreateTaskParams, ListTasksParams

@pytest.mark.asyncio
async def test_create_then_list():
    ctx = MockContext(user_id="imp_u_test")
    res = await create_task(ctx, CreateTaskParams(title="Buy milk"))
    assert res.status == "success"
    listed = await list_tasks(ctx, ListTasksParams(only_pending=True))
    assert listed.data["count"] == 1