Build an extension

​

Quick start

git clone https://github.com/puphq/tricks.git
cd tricks
bun install --frozen-lockfile
cd examples/hello
cp .env.sample .env
bun trick.ts

​

A trick in one file

import { defineTrick, serve, tool, z } from "@puphq/tricks"

serve(
  defineTrick({
    id: "snack_club",
    name: "Snack Club",
    author: "Example author",
    description: "Choose a snack and save your preference.",
    summary: "List snacks or save your preference.",
    instructions: "Use save_snack only when asked to save a preference.",
    tools: {
      save_snack: tool({
        title: "Save your snack preference",
        description: "Save the asker's snack preference.",
        input: z.object({ snack: z.enum(["popcorn", "fruit", "pretzels"]) }),
        run: ({ input, askerId, installationId }) => {
          // Store it keyed by installationId and askerId.
          return { saved: input.snack }
        },
      }),
    },
  }),
)

​

Tools

• run({ input, askerId, channelId, installationId, settings }) receives validated input. Pup has verified who asked, where, and on which server. Never trust IDs that arrive as tool arguments; scope stored data by installationId, and by askerId when it is personal.
• Set userRequest: true only when a tool needs the original request. Its handler then receives userRequest: { messageId, channelId, content } from Pup’s signed context, separate from the assistant-written input. It is the triggering member’s message recorded for that call, not a transcript. Commands and task polling do not supply it. Later edits cannot change an existing call’s snapshot.
• callId, when supplied, is Pup’s stable invocation ID. Persist it with installationId to avoid submitting the same remote work again after a restart. It is not an authorization credential.
• Return data, not messages. Pup’s model reads the result and replies in its own words. It never names your trick or relays raw text from it.
• readOnly: true marks a tool that changes nothing. Any other tool is a write, and Pup may ask the member to approve it first (see Approvals). Use alwaysAsk: true for irreversible writes such as deleting or paying.
• title appears on Pup’s approval card. description tells the model when to use the tool, so be specific.
• Throw for real failures. Pup tells the member something went wrong without showing your error text.

​

Commands and buttons

return {
  choices,
  pup: {
    fields: [{ label: "Choices", value: choices.join(", ") }],
    actions: [
      { id: "save_fruit", label: "Save fruit", tool: "save_snack", arguments: { snack: "fruit" } },
    ],
  },
}

​

Long-running tasks

choose_snack: tool({
  title: "Choose a snack",
  description: "Help the asker pick a snack.",
  readOnly: true,
  run: task(async ({ ask }) => {
    const { taste } = await ask("Sweet or salty?", z.object({ taste: z.enum(["sweet", "salty"]) }))
    return { snack: taste === "sweet" ? "fruit" : "popcorn" }
  }),
}),

​

Events and settings

​

Approvals

• A write needs approval when it is marked alwaysAsk, or when outside content could have steered it: a web page, tool output, saved reply, server guidance, or a message from someone outside the tool’s audience. Incomplete source records also need review. Tools available to everyone never escalate. Reads don’t need approval.
• The card shows the action and its inputs, with Do it, Auto-review, Don’t and Details. Only the asker can answer, within 15 minutes. Details is private and shows the complete inputs and excerpts of the outside content.
• Auto-review enables automatic review for that exact tool definition: next time, two checks run at once. One confirms the action matches what the asker asked for; a separate scan looks for injected instructions in the outside content. If both pass, the write runs and the reply notes it was auto-reviewed. Anything else shows the card. Changing the tool’s definition needs new consent, and members can turn Auto review off at any time.
• alwaysAsk tools always show the card and never offer Auto-review. Writes after hosted web search always need the asker.
• Don’t, or letting the card expire, stops all trick writes for that request.

​

Limits and data

​

Protocol reference

​

Manifest

{
  "manifestVersion": 1,
  "protocolVersion": "2026-07-28",
  "id": "snack_club",
  "name": "Snack Club",
  "author": "Example author",
  "description": "List available snacks.",
  "summary": "Read the available snack choices.",
  "instructions": "Use snack_menu when asked for the available snacks.",
  "endpoints": {
    "challenge": "https://snacks.example.com/challenge",
    "mcp": "https://snacks.example.com/mcp"
  },
  "tools": [{ "name": "snack_menu", "readOnly": true }],
  "commands": [{ "name": "snacks", "description": "See available snacks", "tool": "snack_menu" }],
  "settings": [],
  "events": []
}

​

Signed requests

​

Invocation context

​

Tasks

​

Events