Extensions

import type { ExtensionAPI } from "@opsyhq/wolli";
import { Type } from "typebox";

export default function (wolli: ExtensionAPI) {
  // React to events
  wolli.on("session_start", async (_event, { ui }) => {
    ui.notify("Extension loaded!", "info");
  });

  wolli.on("tool_call", async (event, { ui }) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ui.confirm("Dangerous!", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "Blocked by user" };
    }
  });

  // Register a custom tool
  wolli.registerTool({
    name: "greet",
    label: "Greet",
    description: "Greet someone by name",
    parameters: Type.Object({
      name: Type.String({ description: "Name to greet" }),
    }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return {
        content: [{ type: "text", text: `Hello, ${params.name}!` }],
        details: {},
      };
    },
  });

  // Register a command
  wolli.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, { ui }) => {
      const name = args.trim() || "world";
      ui.notify(`Hello ${name}!`, "info");
    },
  });
}

{
  "extensions": [
    "/path/to/local/extension.ts",
    "/path/to/local/extension/dir"
  ]
}

import type { ExtensionAPI } from "@opsyhq/wolli";

export default function (wolli: ExtensionAPI) {
  // Subscribe to events
  wolli.on("event_name", async (event, { ui }) => {
    // ui for user interaction
    const ok = await ui.confirm("Title", "Are you sure?");
    ui.notify("Done!", "info");
    ui.setStatus("my-ext", "Processing...");  // Footer status
    ui.setWidget("my-ext", ["Line 1", "Line 2"]);  // Widget above editor (default)
  });

  // Register tools, commands, shortcuts, flags
  wolli.registerTool({ ... });
  wolli.registerCommand("name", { ... });
  wolli.registerShortcut("ctrl+x", { ... });
  wolli.registerFlag("my-flag", { ... });
}

import type { ExtensionAPI } from "@opsyhq/wolli";

export default async function (wolli: ExtensionAPI) {
  const response = await fetch("http://localhost:1234/config");
  const config = await response.json();
  // Use config to set up tools, commands, etc.
}

~/.wolli/agents/<name>/extensions/
└── my-extension.ts

~/.wolli/agents/<name>/extensions/
└── my-extension/
    ├── index.ts        # Entry point (exports default function)
    ├── tools.ts        # Helper module
    └── utils.ts        # Helper module

~/.wolli/agents/<name>/extensions/
└── my-extension/
    ├── package.json    # Declares dependencies and entry points
    ├── package-lock.json
    ├── node_modules/   # After npm install
    └── src/
        └── index.ts

// package.json
{
  "name": "my-extension",
  "dependencies": {
    "zod": "^3.0.0",
    "chalk": "^5.0.0"
  },
  "wolli": {
    "extensions": ["./src/index.ts"]
  }
}

Wolli starts
  │
  └─► session_start { reason: "startup" }
      │
      ▼
user sends prompt ─────────────────────────────────────────┐
  │                                                        │
  ├─► (extension commands checked first, bypass if found)  │
  ├─► input (can intercept, transform, or handle)          │
  ├─► (skill/template expansion if not handled)            │
  ├─► before_agent_start (can inject message, modify system prompt)
  ├─► agent_start                                          │
  ├─► message_start / message_update / message_end         │
  │                                                        │
  │   ┌─── turn (repeats while LLM calls tools) ───┐       │
  │   │                                            │       │
  │   ├─► turn_start                               │       │
  │   ├─► context (can modify messages)            │       │
  │   ├─► before_provider_request (can inspect or replace payload)
  │   │                                            │       │
  │   │   LLM responds, may call tools:            │       │
  │   │     ├─► tool_execution_start               │       │
  │   │     ├─► tool_call (can block)              │       │
  │   │     ├─► tool_execution_update              │       │
  │   │     ├─► tool_result (can modify)           │       │
  │   │     └─► tool_execution_end                 │       │
  │   │                                            │       │
  │   └─► turn_end                                 │       │
  │                                                        │
  └─► agent_end                                            │
                                                           │
user sends another prompt ◄────────────────────────────────┘

/new (new session) or /sessions (switch session)
  ├─► session_shutdown
  └─► session_start { reason: "new" | "resume", previousSessionFile? }

/compact or auto-compaction
  └─► session_before_compact (can cancel or customize)

/model or Ctrl+P (model selection/cycling)
  ├─► thinking_level_select (if model change changes/clamps thinking level)
  └─► model_select

thinking level changes (settings, keybinding, ctx.session.setThinkingLevel())
  └─► thinking_level_select

exit (Ctrl+C, Ctrl+D, SIGHUP, SIGTERM)
  └─► session_shutdown

for each extension (in extension load order)
  for each handler that extension registered for this event (in registration order)
    await handler(event, ctx)

wolli.on("session_start", async (event, { session, ui }) => {
  // event.reason - "startup" | "reload" | "new" | "resume" | "fork"
  // event.previousSessionFile - present for "new", "resume", and "fork"
  ui.notify(`Session: ${session.sessionManager.getSessionFile() ?? "ephemeral"}`, "info");
});

wolli.on("session_before_compact", async (event, ctx) => {
  const { preparation, branchEntries, customInstructions, signal } = event;

  // Cancel:
  return { cancel: true };

  // Custom summary:
  return {
    compaction: {
      summary: "...",
      firstKeptEntryId: preparation.firstKeptEntryId,
      tokensBefore: preparation.tokensBefore,
    }
  };
});

wolli.on("session_shutdown", async (event, ctx) => {
  // event.reason - "quit" | "reload" | "new" | "resume" | "fork"
  // event.targetSessionFile - destination session for session replacement flows
  // Cleanup, save state, etc.
});

wolli.on("before_agent_start", async (event, ctx) => {
  // event.prompt - user's prompt text
  // event.images - attached images (if any)
  // event.systemPrompt - current chained system prompt for this handler
  //   (includes changes from earlier before_agent_start handlers)
  // event.systemPromptOptions - structured options used to build the system prompt
  //   .config - the agent config (present at the real call site)
  //   .cwd - working directory
  //   .soul - frozen SOUL.md snapshot ("" when absent)
  //   .memory - frozen MEMORY.md snapshot ("" when absent)
  //   .user - frozen USER.md snapshot ("" when absent)
  //   .skills - skills discovered for this agent
  //   .selectedTools - names of the tools active this session
  //   .appendSystemPrompt - text appended to the end of the system prompt

  return {
    // Inject a persistent message (stored in session, sent to LLM)
    message: {
      customType: "my-extension",
      content: "Additional context for the LLM",
      display: true,
    },
    // Replace the system prompt for this turn (chained across extensions)
    systemPrompt: event.systemPrompt + "\n\nExtra instructions for this turn...",
  };
});

wolli.on("agent_start", async (_event, ctx) => {});

wolli.on("agent_end", async (event, ctx) => {
  // event.messages - messages from this prompt
});

wolli.on("turn_start", async (event, ctx) => {
  // event.turnIndex, event.timestamp
});

wolli.on("turn_end", async (event, ctx) => {
  // event.turnIndex, event.message, event.toolResults
});

wolli.on("message_start", async (event, ctx) => {
  // event.message
});

wolli.on("message_update", async (event, ctx) => {
  // event.message
  // event.assistantMessageEvent (token-by-token stream event)
});

wolli.on("message_end", async (event, ctx) => {
  if (event.message.role !== "assistant") return;

  return {
    message: {
      ...event.message,
      usage: {
        ...event.message.usage,
        cost: {
          ...event.message.usage.cost,
          total: 0.123,
        },
      },
    },
  };
});

wolli.on("tool_execution_start", async (event, ctx) => {
  // event.toolCallId, event.toolName, event.args
});

wolli.on("tool_execution_update", async (event, ctx) => {
  // event.toolCallId, event.toolName, event.args, event.partialResult
});

wolli.on("tool_execution_end", async (event, ctx) => {
  // event.toolCallId, event.toolName, event.result, event.isError
});

wolli.on("context", async (event, ctx) => {
  // event.messages - deep copy, safe to modify
  const filtered = event.messages.filter(m => !shouldPrune(m));
  return { messages: filtered };
});

wolli.on("before_provider_request", (event, ctx) => {
  console.log(JSON.stringify(event.payload, null, 2));

  // Optional: replace payload
  // return { ...event.payload, temperature: 0 };
});

wolli.on("model_select", async (event, { ui }) => {
  // event.model - newly selected model
  // event.previousModel - previous model (undefined if first selection)
  // event.source - "set" | "cycle" | "restore"

  const prev = event.previousModel
    ? `${event.previousModel.provider}/${event.previousModel.id}`
    : "none";
  const next = `${event.model.provider}/${event.model.id}`;

  ui.notify(`Model changed (${event.source}): ${prev} -> ${next}`, "info");
});

wolli.on("thinking_level_select", async (event, { ui }) => {
  // event.level - newly selected thinking level
  // event.previousLevel - previous thinking level

  ui.setStatus("thinking", `thinking: ${event.level}`);
});

import { isToolCallEventType } from "@opsyhq/wolli";

wolli.on("tool_call", async (event, ctx) => {
  // event.toolName - "bash", "read", "write", "edit", etc.
  // event.toolCallId
  // event.input - tool parameters (mutable)

  // Built-in tools: no type params needed
  if (isToolCallEventType("bash", event)) {
    // event.input is { command: string; timeout?: number }
    event.input.command = `source ~/.profile\n${event.input.command}`;

    if (event.input.command.includes("rm -rf")) {
      return { block: true, reason: "Dangerous command" };
    }
  }

  if (isToolCallEventType("read", event)) {
    // event.input is { path: string; offset?: number; limit?: number }
    console.log(`Reading: ${event.input.path}`);
  }
});

// my-extension.ts
export type MyToolInput = Static<typeof myToolSchema>;

import { isToolCallEventType } from "@opsyhq/wolli";
import type { MyToolInput } from "my-extension";

wolli.on("tool_call", (event) => {
  if (isToolCallEventType<"my_tool", MyToolInput>("my_tool", event)) {
    event.input.action;  // typed
  }
});

import { isBashToolResult } from "@opsyhq/wolli";

wolli.on("tool_result", async (event, { session }) => {
  // event.toolName, event.toolCallId, event.input
  // event.content, event.details, event.isError

  if (isBashToolResult(event)) {
    // event.details is typed as BashToolDetails
  }

  const response = await fetch("https://example.com/summarize", {
    method: "POST",
    body: JSON.stringify({ content: event.content }),
    signal: session.signal,
  });

  // Modify result:
  return { content: [...], details: {...}, isError: false };
});

import { createHostEnvironment } from "@opsyhq/wolli";

wolli.on("user_bash", (event, ctx) => {
  // event.command - the bash command
  // event.excludeFromContext - true if !! prefix
  // event.cwd - working directory

  // Option 1: Run the command in a custom environment (e.g., a sandbox)
  return { environment: customEnvironment };

  // Option 2: Wrap Wolli's host environment to rewrite commands
  const host = createHostEnvironment(event.cwd);
  return {
    environment: {
      ...host,
      exec: (command, cwd, options) => host.exec(`source ~/.profile\n${command}`, cwd, options),
    },
  };

  // Option 3: Full replacement - return result directly
  return { result: { output: "...", exitCode: 0, cancelled: false, truncated: false } };
});

wolli.on("input", async (event, { ui }) => {
  // event.text - raw input (before skill/template expansion)
  // event.images - attached images, if any
  // event.source - "interactive" (typed), "rpc", or "extension" (via sendUserMessage)
  // event.streamingBehavior - "steer" | "followUp" | undefined
  //   undefined when idle, "steer" for mid-stream interrupts,
  //   "followUp" for messages queued until the agent finishes

  // Transform: rewrite input before expansion
  if (event.text.startsWith("?quick "))
    return { action: "transform", text: `Respond briefly: ${event.text.slice(7)}` };

  // Handle: respond without LLM (extension shows its own feedback)
  if (event.text === "ping") {
    ui.notify("pong", "info");
    return { action: "handled" };
  }

  // Route by source: skip processing for extension-injected messages
  if (event.source === "extension") return { action: "continue" };

  // Intercept skill commands before expansion
  if (event.text.startsWith("/skill:")) {
    // Could transform, block, or let pass through
  }

  return { action: "continue" };  // Default: pass through to expansion
});

interface ExtensionContext {
  session: Session;          // the live session this handler/tool/command acts on
  ui: ExtensionUIContext;    // that session's presentation channel
  mode: ExtensionMode;       // "tui" | "rpc" | "json" | "print"
}

session.sessionManager.getEntries()       // All entries
session.sessionManager.getBranch()        // Current branch
session.sessionManager.getLeafId()        // Current leaf entry ID
session.sessionManager.getLabel(entryId)  // Label on an entry, if any
session.sessionManager.getSessionFile()   // Session file path, or undefined

wolli.on("tool_result", async (event, { session }) => {
  const response = await fetch("https://example.com/api", {
    method: "POST",
    body: JSON.stringify(event),
    signal: session.signal,
  });

  const data = await response.json();
  return { details: data };
});

wolli.registerCommand("my-cmd", {
  handler: async (args, { session }) => {
    await session.waitForIdle();
    // Agent is now idle, safe to modify session
  },
});

const usage = session.getContextUsage();
if (usage && usage.tokens !== null && usage.tokens > 100_000) {
  // ...
}

session.compact({
  customInstructions: "Focus on recent changes",
  onComplete: (result) => {
    ui.notify("Compaction completed", "info");
  },
  onError: (error) => {
    ui.notify(`Compaction failed: ${error.message}`, "error");
  },
});

wolli.on("before_agent_start", (event, { session }) => {
  const prompt = session.getSystemPrompt();
  console.log(`System prompt length: ${prompt.length}`);
});

const options = session.getSystemPromptOptions();
const activeToolNames = options.selectedTools ?? [];

sendMessage<T = unknown>(
  message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
  options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
): void;

session.sendMessage({
  customType: "my-extension",
  content: "Message text",
  display: true,
  details: { ... },
}, {
  triggerTurn: true,
  deliverAs: "steer",
});

// Simple text message
session.sendUserMessage("What is 2+2?");

// With content array (text + images)
session.sendUserMessage([
  { type: "text", text: "Describe this image:" },
  { type: "image", source: { type: "base64", mediaType: "image/png", data: "..." } },
]);

// During streaming - must specify delivery mode
session.sendUserMessage("Focus on error handling", { deliverAs: "steer" });
session.sendUserMessage("And then summarize", { deliverAs: "followUp" });

wolli.on("session_start", async (_event, { session }) => {
  session.appendEntry("my-state", { count: 42 });

  // Restore on reload
  for (const entry of session.sessionManager.getEntries()) {
    if (entry.type === "custom" && entry.customType === "my-state") {
      // Reconstruct from entry.data
    }
  }
});

session.setSessionName("Refactor auth module");

const name = session.getSessionName();
if (name) {
  console.log(`Session: ${name}`);
}

// Set a label
session.setLabel(entryId, "checkpoint-before-refactor");

// Clear a label
session.setLabel(entryId, undefined);

// Read labels via sessionManager
const label = session.sessionManager.getLabel(entryId);

session.setTags({ "telegram:chat": String(chatId) });

const tags = session.getTags();
const chat = tags["telegram:chat"];

const commands = session.getCommands();
const fromExtensions = commands.filter((command) => command.source === "extension");
const userScoped = commands.filter((command) => command.sourceInfo.scope === "user");

{
  name: string; // Invokable command name without the leading slash. May be suffixed like "review:1"
  description?: string;
  source: "extension" | "prompt" | "skill";
  sourceInfo: SourceInfo;  // { path, source, scope, origin, baseDir? }
}

const active = session.getActiveTools();
const all = session.getAllTools();
// [{
//   name: "read",
//   description: "Read file contents...",
//   parameters: ...,
//   promptGuidelines: ["Use read to examine files instead of cat or sed."],
//   sourceInfo: { path: "<builtin:read>", source: "builtin", scope: "temporary", origin: "top-level" }
// }, ...]
const names = all.map(t => t.name);
const builtinTools = all.filter((t) => t.sourceInfo.source === "builtin");
const extensionTools = all.filter((t) => t.sourceInfo.source !== "builtin" && t.sourceInfo.source !== "sdk");
session.setActiveTools(["read", "bash"]); // Switch to read-only

const model = wolli.modelRegistry.find("anthropic", "claude-sonnet-4-5");
if (model) {
  const success = await session.setModel(model);
  if (!success) {
    ui.notify("No API key for this model", "error");
  }
}

const current = session.getThinkingLevel();  // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
await session.setThinkingLevel("high");

const kickoff = "Continue in the replacement session";

const result = await session.newSession({
  setup: async (sm) => {
    sm.appendMessage({
      role: "user",
      content: [{ type: "text", text: "Context from previous session..." }],
      timestamp: Date.now(),
    });
  },
  withSession: async (newSession) => {
    // Use only the replacement session here.
    await newSession.sendUserMessage(kickoff);
  },
});

if (result.cancelled) {
  // An extension cancelled the new session
}

wolli.registerCommand("reload-runtime", {
  description: "Reload extensions, skills, prompts, and themes",
  handler: async (_args, { session }) => {
    await session.reload();
    return;
  },
});

import type { ExtensionAPI } from "@opsyhq/wolli";
import { Type } from "typebox";

export default function (wolli: ExtensionAPI) {
  wolli.registerCommand("reload-runtime", {
    description: "Reload extensions, skills, prompts, and themes",
    handler: async (_args, { session }) => {
      await session.reload();
      return;
    },
  });

  wolli.registerTool({
    name: "reload_runtime",
    label: "Reload Runtime",
    description: "Reload extensions, skills, prompts, and themes",
    parameters: Type.Object({}),
    async execute(toolCallId, params, signal, onUpdate, { session }) {
      session.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });
      return {
        content: [{ type: "text", text: "Queued /reload-runtime as a follow-up command." }],
        details: {},
      };
    },
  });
}

wolli.registerCommand("handoff", {
  handler: async (_args, { session }) => {
    const kickoff = "Continue from the replacement session";
    await session.newSession({
      withSession: async (newSession) => {
        await newSession.sendUserMessage(kickoff);
      },
    });
  },
});

wolli.registerCommand("handoff", {
  handler: async (_args, { session }) => {
    const oldSessionManager = session.sessionManager;
    await session.newSession({
      withSession: async (_newSession) => {
        // stale old objects: do not do this
        oldSessionManager.getSessionFile();
        session.sendUserMessage("wrong");
      },
    });
  },
});

import { Type } from "typebox";
import { StringEnum } from "@earendil-works/pi-ai";

wolli.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "What this tool does",
  promptSnippet: "Summarize or transform text according to action",
  promptGuidelines: ["Use my_tool when the user asks to summarize previously generated text."],
  parameters: Type.Object({
    action: StringEnum(["list", "add"] as const),
    text: Type.Optional(Type.String()),
  }),
  prepareArguments(args) {
    // Optional compatibility shim. Runs before schema validation.
    // Return the current schema shape, for example to fold legacy fields
    // into the modern parameter object.
    return args;
  },

  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // Stream progress
    onUpdate?.({ content: [{ type: "text", text: "Working..." }] });

    return {
      content: [{ type: "text", text: "Done" }],
      details: { result: "..." },
    };
  },

  // Optional: Custom rendering
  renderCall(args, theme, context) { ... },
  renderResult(result, options, theme, context) { ... },
});

wolli.registerCommand("stats", {
  description: "Show session statistics",
  handler: async (args, { session, ui }) => {
    const count = session.sessionManager.getEntries().length;
    ui.notify(`${count} entries`, "info");
  }
});

import type { AutocompleteItem } from "@opsyhq/tui";

wolli.registerCommand("deploy", {
  description: "Deploy to an environment",
  getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
    const envs = ["dev", "staging", "prod"];
    const items = envs.map((e) => ({ value: e, label: e }));
    const filtered = items.filter((i) => i.value.startsWith(prefix));
    return filtered.length > 0 ? filtered : null;
  },
  handler: async (args, { ui }) => {
    ui.notify(`Deploying: ${args}`, "info");
  },
});

wolli.registerShortcut("ctrl+shift+p", {
  description: "Toggle plan mode",
  handler: async ({ ui }) => {
    ui.notify("Toggled!");
  },
});

wolli.registerFlag("plan", {
  description: "Start in plan mode",
  type: "boolean",
  default: false,
});

// Check value
if (wolli.getFlag("plan")) {
  // Plan mode enabled
}

// Reach (or create) the session bound to an external chat, from a background callback.
const [match] = await wolli.findSessions({ "telegram:chat": String(chatId) });
const session = match ? await wolli.openSession(match.id) : await wolli.createSession();
await session.sendUserMessage("Triggered from a background callback");

wolli.on("tool_call", (event) => {
  if (isFatal(event.input)) {
    wolli.shutdown();
  }
});

wolli.events.on("my:event", (data) => { ... });
wolli.events.emit("my:event", { ... });

export default function (wolli: ExtensionAPI) {
  let items: string[] = [];

  // Reconstruct state from session
  wolli.on("session_start", async (_event, { session }) => {
    items = [];
    for (const entry of session.sessionManager.getBranch()) {
      if (entry.type === "message" && entry.message.role === "toolResult") {
        if (entry.message.toolName === "my_tool") {
          items = entry.message.details?.items ?? [];
        }
      }
    }
  });

  wolli.registerTool({
    name: "my_tool",
    // ...
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      items.push("new item");
      return {
        content: [{ type: "text", text: "Added" }],
        details: { items: [...items] },  // Store for reconstruction
      };
    },
  });
}

wolli.on("session_start", (_event, { session }) => {
  for (const entry of session.sessionManager.getBranch()) {
    if (entry.type === "custom_message" && entry.customType === "my-extension") {
      // entry.content - string | (TextContent | ImageContent)[]
      // entry.details - the payload you passed to sendMessage
      // entry.display - boolean
      const restored = entry.details as { notes?: string[] };
      // reconstruct from restored.notes...
    }
  }
});

import { withFileMutationQueue } from "@opsyhq/wolli";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { dirname, resolve } from "node:path";

async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
  const absolutePath = resolve(wolli.cwd, params.path);

  return withFileMutationQueue(absolutePath, async () => {
    await mkdir(dirname(absolutePath), { recursive: true });
    const current = await readFile(absolutePath, "utf8");
    const next = current.replace(params.oldText, params.newText);
    await writeFile(absolutePath, next, "utf8");

    return {
      content: [{ type: "text", text: `Updated ${params.path}` }],
      details: {},
    };
  });
}

import { Type } from "typebox";
import { StringEnum } from "@earendil-works/pi-ai";
import { Text } from "@opsyhq/tui";
import { execFile } from "node:child_process";
import { promisify } from "node:util";

const execFileAsync = promisify(execFile);

wolli.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "What this tool does (shown to LLM)",
  promptSnippet: "List or add items in the project todo list",
  promptGuidelines: [
    "Use my_tool for todo planning instead of direct file edits when the user asks for a task list."
  ],
  parameters: Type.Object({
    action: StringEnum(["list", "add"] as const),  // Use StringEnum for Google compatibility
    text: Type.Optional(Type.String()),
  }),
  prepareArguments(args) {
    if (!args || typeof args !== "object") return args;
    const input = args as { action?: string; oldAction?: string };
    if (typeof input.oldAction === "string" && input.action === undefined) {
      return { ...input, action: input.oldAction };
    }
    return args;
  },

  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // Check for cancellation
    if (signal?.aborted) {
      return { content: [{ type: "text", text: "Cancelled" }], details: {} };
    }

    // Stream progress updates
    onUpdate?.({
      content: [{ type: "text", text: "Working..." }],
      details: { progress: 50 },
    });

    // Run commands with Node's child_process
    const result = await execFileAsync("some-command", [], { signal });

    // Return result
    return {
      content: [{ type: "text", text: "Done" }],  // Sent to LLM
      details: { data: result },                   // For rendering & state
      // Optional: stop after this tool batch when every finalized tool result
      // in the batch also returns terminate: true.
      terminate: true,
    };
  },

  // Optional: Custom rendering
  renderCall(args, theme, context) { ... },
  renderResult(result, options, theme, context) { ... },
});

// Correct: throw to signal an error
async execute(toolCallId, params) {
  if (!isValid(params.input)) {
    throw new Error(`Invalid input: ${params.input}`);
  }
  return { content: [{ type: "text", text: "OK" }], details: {} };
}

wolli.registerTool({
  name: "edit",
  label: "Edit",
  description: "Edit a single file using exact text replacement",
  parameters: Type.Object({
    path: Type.String(),
    edits: Type.Array(
      Type.Object({
        oldText: Type.String(),
        newText: Type.String(),
      }),
    ),
  }),
  prepareArguments(args) {
    if (!args || typeof args !== "object") return args;

    const input = args as {
      path?: string;
      edits?: Array<{ oldText: string; newText: string }>;
      oldText?: unknown;
      newText?: unknown;
    };

    if (typeof input.oldText !== "string" || typeof input.newText !== "string") {
      return args;
    }

    return {
      ...input,
      edits: [...(input.edits ?? []), { oldText: input.oldText, newText: input.newText }],
    };
  },
  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // params now matches the current schema
    return {
      content: [{ type: "text", text: `Applying ${params.edits.length} edit block(s)` }],
      details: {},
    };
  },
});

import { createBashTool, createReadTool, type Environment } from "@opsyhq/wolli";

// Reach the default target environment, then build a tool against a custom
// environment (e.g. one that wraps exec)
const base = wolli.environments.targets[wolli.environments.default];
const env: Environment = {
  ...base,
  exec: (command, cwd, options) => base.exec(`source ~/.profile\n${command}`, cwd, options),
};
const customBash = createBashTool(env);

import { createBashTool, createHostEnvironment } from "@opsyhq/wolli";

const env = createHostEnvironment(wolli.cwd);
const bashTool = createBashTool(env, {
  spawnHook: ({ command, cwd, env }) => ({
    command: `source ~/.profile\n${command}`,
    cwd: `/mnt/sandbox${cwd}`,
    env: { ...env, CI: "1" },
  }),
});

import {
  truncateHead,      // Keep first N lines/bytes (good for file reads, search results)
  truncateTail,      // Keep last N lines/bytes (good for logs, command output)
  truncateLine,      // Truncate a single line to maxBytes with ellipsis
  formatSize,        // Human-readable size (e.g., "50KB", "1.5MB")
  DEFAULT_MAX_BYTES, // 50KB
  DEFAULT_MAX_LINES, // 2000
} from "@opsyhq/wolli";

async execute(toolCallId, params, signal, onUpdate, ctx) {
  const output = await runCommand();

  // Apply truncation
  const truncation = truncateHead(output, {
    maxLines: DEFAULT_MAX_LINES,
    maxBytes: DEFAULT_MAX_BYTES,
  });

  let result = truncation.content;

  if (truncation.truncated) {
    // Write full output to temp file
    const tempFile = writeTempFile(output);

    // Inform the LLM where to find complete output
    result += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines`;
    result += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).`;
    result += ` Full output saved to: ${tempFile}]`;
  }

  return { content: [{ type: "text", text: result }] };
}

export default function (wolli: ExtensionAPI) {
  let connection = null;

  wolli.registerTool({ name: "db_connect", ... });
  wolli.registerTool({ name: "db_query", ... });
  wolli.registerTool({ name: "db_close", ... });

  wolli.on("session_shutdown", async () => {
    connection?.close();
  });
}

wolli.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "Custom shell example",
  parameters: Type.Object({}),
  renderShell: "self",
  async execute() {
    return { content: [{ type: "text", text: "ok" }], details: undefined };
  },
  renderCall(args, theme, context) {
    return new Text(theme.fg("accent", "my custom shell"), 0, 0);
  },
});

import { Text } from "@opsyhq/tui";

renderCall(args, theme, context) {
  const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
  let content = theme.fg("toolTitle", theme.bold("my_tool "));
  content += theme.fg("muted", args.action);
  if (args.text) {
    content += " " + theme.fg("dim", `"${args.text}"`);
  }
  text.setText(content);
  return text;
}

renderResult(result, { expanded, isPartial }, theme, context) {
  if (isPartial) {
    return new Text(theme.fg("warning", "Processing..."), 0, 0);
  }

  if (result.details?.error) {
    return new Text(theme.fg("error", `Error: ${result.details.error}`), 0, 0);
  }

  let text = theme.fg("success", "✓ Done");
  if (expanded && result.details?.items) {
    for (const item of result.details.items) {
      text += "\n  " + theme.fg("dim", item);
    }
  }
  return new Text(text, 0, 0);
}

import { keyHint } from "@opsyhq/wolli";

renderResult(result, { expanded }, theme, context) {
  let text = theme.fg("success", "✓ Done");
  if (!expanded) {
    text += ` (${keyHint("app.tools.expand", "to expand")})`;
  }
  return new Text(text, 0, 0);
}

// Select from options
const choice = await ui.select("Pick one:", ["A", "B", "C"]);

// Confirm dialog
const ok = await ui.confirm("Delete?", "This cannot be undone");

// Text input
const name = await ui.input("Name:", "placeholder");

// Multi-line editor
const text = await ui.editor("Edit:", "prefilled text");

// Notification (non-blocking)
ui.notify("Done!", "info");  // "info" | "warning" | "error"

// Dialog shows "Title (5s)" → "Title (4s)" → ... → auto-dismisses at 0
const confirmed = await ui.confirm(
  "Timed Confirmation",
  "This dialog will auto-cancel in 5 seconds. Confirm?",
  { timeout: 5000 }
);

if (confirmed) {
  // User confirmed
} else {
  // User cancelled or timed out
}

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000);

const confirmed = await ui.confirm(
  "Timed Confirmation",
  "This dialog will auto-cancel in 5 seconds. Confirm?",
  { signal: controller.signal }
);

clearTimeout(timeoutId);

if (confirmed) {
  // User confirmed
} else if (controller.signal.aborted) {
  // Dialog timed out
} else {
  // User cancelled (pressed Escape or selected "No")
}

// Status in footer (persistent until cleared)
ui.setStatus("my-ext", "Processing...");
ui.setStatus("my-ext", undefined);  // Clear

// Working loader (shown during streaming)
ui.setWorkingMessage("Thinking deeply...");
ui.setWorkingMessage();  // Restore default
ui.setWorkingVisible(false);  // Hide the built-in working loader row entirely
ui.setWorkingVisible(true);   // Show the built-in working loader row

// Working indicator (shown during streaming)
ui.setWorkingIndicator({ frames: [ui.theme.fg("accent", "●")] });  // Static dot
ui.setWorkingIndicator({
  frames: [
    ui.theme.fg("dim", "·"),
    ui.theme.fg("muted", "•"),
    ui.theme.fg("accent", "●"),
    ui.theme.fg("muted", "•"),
  ],
  intervalMs: 120,
});
ui.setWorkingIndicator({ frames: [] });  // Hide indicator
ui.setWorkingIndicator();  // Restore default spinner

// Widget above editor (default)
ui.setWidget("my-widget", ["Line 1", "Line 2"]);
// Widget below editor
ui.setWidget("my-widget", ["Line 1", "Line 2"], { placement: "belowEditor" });
ui.setWidget("my-widget", (tui, theme) => new Text(theme.fg("accent", "Custom"), 0, 0));
ui.setWidget("my-widget", undefined);  // Clear

// Custom footer (replaces built-in footer entirely)
ui.setFooter((tui, theme) => ({
  render(width) { return [theme.fg("dim", "Custom footer")]; },
  invalidate() {},
}));
ui.setFooter(undefined);  // Restore built-in footer

// Terminal title
ui.setTitle("wolli - my-agent");

// Editor text
ui.setEditorText("Prefill text");
const current = ui.getEditorText();

// Paste into editor (triggers paste handling, including collapse for large content)
ui.pasteToEditor("pasted content");

// Stack custom autocomplete behavior on top of the built-in provider
ui.addAutocompleteProvider((current) => ({
  triggerCharacters: ["#"],
  async getSuggestions(lines, line, col, options) {
    const beforeCursor = (lines[line] ?? "").slice(0, col);
    const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
    if (!match) {
      return current.getSuggestions(lines, line, col, options);
    }

    return {
      prefix: `#${match[1] ?? ""}`,
      items: [{ value: "#2983", label: "#2983", description: "Extension API for autocomplete" }],
    };
  },
  applyCompletion(lines, line, col, item, prefix) {
    return current.applyCompletion(lines, line, col, item, prefix);
  },
  shouldTriggerFileCompletion(lines, line, col) {
    return current.shouldTriggerFileCompletion?.(lines, line, col) ?? true;
  },
}));

// Tool output expansion
const wasExpanded = ui.getToolsExpanded();
ui.setToolsExpanded(true);
ui.setToolsExpanded(wasExpanded);

// Custom editor (vim mode, emacs mode, etc.)
ui.setEditorComponent((tui, theme, keybindings) => new VimEditor(tui, theme, keybindings));
const currentEditor = ui.getEditorComponent();
ui.setEditorComponent((tui, theme, keybindings) =>
  new WrappedEditor(tui, theme, keybindings, currentEditor?.(tui, theme, keybindings))
);
ui.setEditorComponent(undefined);  // Restore default editor

// Theme management (see themes.md for creating themes)
const themes = ui.getAllThemes();  // [{ name: "dark", path: "/..." | undefined }, ...]
const lightTheme = ui.getTheme("light");  // Load without switching
const result = ui.setTheme("light");  // Switch by name
if (!result.success) {
  ui.notify(`Failed: ${result.error}`, "error");
}
ui.setTheme(lightTheme!);  // Or switch by Theme object
ui.theme.fg("accent", "styled text");  // Access current theme

wolli.on("session_start", (_event, { ui }) => {
  ui.addAutocompleteProvider((current) => ({
    triggerCharacters: ["#"],
    async getSuggestions(lines, cursorLine, cursorCol, options) {
      const line = lines[cursorLine] ?? "";
      const beforeCursor = line.slice(0, cursorCol);
      const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
      if (!match) {
        return current.getSuggestions(lines, cursorLine, cursorCol, options);
      }

      return {
        prefix: `#${match[1] ?? ""}`,
        items: [
          { value: "#2983", label: "#2983", description: "Extension API for registering custom @ autocomplete providers" },
          { value: "#2753", label: "#2753", description: "Reload stale resource settings" },
        ],
      };
    },

    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
    },

    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
    },
  }));
});

import { Text, Component } from "@opsyhq/tui";

const result = await ui.custom<boolean>((tui, theme, keybindings, done) => {
  const text = new Text("Press Enter to confirm, Escape to cancel", 1, 1);

  text.onKey = (key) => {
    if (key === "return") done(true);
    if (key === "escape") done(false);
    return true;
  };

  return text;
});

if (result) {
  // User pressed Enter
}

import { CustomEditor, type ExtensionAPI } from "@opsyhq/wolli";
import { matchesKey } from "@opsyhq/tui";

class VimEditor extends CustomEditor {
  private mode: "normal" | "insert" = "insert";

  handleInput(data: string): void {
    if (matchesKey(data, "escape") && this.mode === "insert") {
      this.mode = "normal";
      return;
    }
    if (this.mode === "normal" && data === "i") {
      this.mode = "insert";
      return;
    }
    super.handleInput(data);  // App keybindings + text editing
  }
}

export default function (wolli: ExtensionAPI) {
  wolli.on("session_start", (_event, { ui }) => {
    ui.setEditorComponent((tui, theme, keybindings) =>
      new VimEditor(tui, theme, keybindings)
    );
  });
}

const previous = ui.getEditorComponent();
ui.setEditorComponent((tui, theme, keybindings) =>
  new MyEditor(tui, theme, keybindings, { base: previous?.(tui, theme, keybindings) })
);

import { Text } from "@opsyhq/tui";

wolli.registerMessageRenderer("my-extension", (message, options, theme) => {
  const { expanded } = options;
  let text = theme.fg("accent", `[${message.customType}] `);
  text += message.content;

  if (expanded && message.details) {
    text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
  }

  return new Text(text, 0, 0);
});

session.sendMessage({
  customType: "my-extension",  // Matches registerMessageRenderer
  content: "Status update",
  display: true,               // Show in TUI
  details: { ... },            // Available in renderer
});