Adding a Tool

// server/protocol/handlers/myfeature.js
export async function executeMyTool(block, ctx) {
  // block.attrs   — tag attributes
  // block.body    — inner text (CDATA-unwrapped)
  // block.children — typed sub-tags (if your tool uses them)
  // ctx           — per-request context: audit(), emit(), signal, loadConfig(), …

  const target = (block.attrs?.target || '').trim();
  if (!target) {
    return { ok: false, event: 'tool_error', payload: { tag: 'my_tool', reason: 'target required' }, llmEcho: 'my_tool: target required' };
  }

  // …do the work…
  await ctx.audit({ kind: 'my_tool', target });

  return {
    ok: true,
    event: 'my_tool',                 // SSE event name → the presence
    payload: { target, result: '…' }, // card data for the bubble
    llmEcho: `Did the thing to ${target}.`, // what the model reads next pass
    // llmMedia: [{ type: 'image_url', url, mediaType, label }]  // optional images for the model
  };
}

my_tool: {
  description: "What it does. This text is rendered into the system prompt, so be precise about when and how to use it.",
  params: {
    attrs: { target: 'required. the thing to act on.' },
    body: 'optional text payload',
    // children: { … }  // if your tool takes typed sub-tags
  },
  examples: [`<my_tool target="x"/>`],
  voiced: false,        // does its run surface in the bubble?
  feedsBack: true,      // does its result trigger another model pass? (usually yes)
  execute: myfeature.executeMyTool,
},