Custom Tools

// my-plugin/src/tools/weather.ts
import { z } from 'zod';
import type { ToolDefinition, ToolResult, ToolExecutionContext } from 'profclaw/sdk';

const WeatherParamsSchema = z.object({
  city: z.string().describe('City name'),
  units: z.enum(['celsius', 'fahrenheit']).optional().default('celsius'),
});

export const weatherTool: ToolDefinition = {
  name: 'get_weather',
  description: 'Get current weather for a city.',
  category: 'custom',
  securityLevel: 'safe',
  parameters: WeatherParamsSchema,

  async execute(
    context: ToolExecutionContext,
    params: z.infer<typeof WeatherParamsSchema>
  ): Promise<ToolResult> {
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${params.city}`
    );
    const data = await response.json();
    return {
      success: true,
      output: `${params.city}: ${data.main.temp}°, ${data.weather[0].description}`,
    };
  },
};

import type { PluginContext } from 'profclaw/sdk';
import { weatherTool } from './tools/weather.js';

export function activate(ctx: PluginContext): void {
  ctx.tools.register(weatherTool);
}

// Success
return {
  success: true,
  data: { /* structured data for the model */ },
  output: "Human-readable summary shown to the model",
};

// Error
return {
  success: false,
  error: {
    code: 'FETCH_ERROR',
    message: 'Could not connect to weather API',
    retryable: true,
  },
};

interface ToolExecutionContext {
  toolCallId: string;      // Unique ID for this call
  conversationId: string;  // Current conversation
  userId?: string;         // Authenticated user if any
  workdir: string;         // Working directory
  env: Record<string, string>; // Allowed environment vars
  securityPolicy: SecurityPolicy; // Active security policy
  signal?: AbortSignal;    // Cancellation signal
  sessionManager: SessionManager; // Session CRUD
}

---
name: my-command
description: My custom slash command
command-dispatch: tool
command-tool: exec
command-arg-mode: raw
---

Run my custom script with the provided arguments.

export const myTool: ToolDefinition = {
  name: 'my_simple_tool',
  tier: 'standard', // Available to 14B+ models
  // ...
};

import { describe, it, expect } from 'vitest';
import { weatherTool } from './tools/weather.js';

describe('get_weather', () => {
  it('returns weather for a valid city', async () => {
    const ctx = createMockContext({ workdir: '/tmp' });
    const result = await weatherTool.execute(ctx, { city: 'London' });
    expect(result.success).toBe(true);
    expect(result.output).toContain('London');
  });
});