Tools Architecture & Reference

1import { ToolDefinition, createAgent } from '@smoke-monkey/harness';
2
3// 1. Define your custom backend tool
4export const deployStagingTool: ToolDefinition = {
5  name: 'deploy_staging', // Unique snake_case identifier
6  description:
7    'Deploys the compiled application to the staging environment. ' +
8    'Call this only after tests have passed in the verify phase. ' +
9    'Requires target git branch and environment confirmation.',
10  inputSchema: {
11    type: 'object',
12    properties: {
13      branch: { type: 'string', description: 'Git branch to deploy (e.g. main, staging)' },
14      dryRun: { type: 'boolean', description: 'Simulate deployment without updating remote' },
15    },
16    required: ['branch'],
17  },
18  // Annotations drive loop behavior:
19  annotations: {
20    destructiveHint: true, // Triggers Pause 1 (Permission Gate) before execution
21  },
22  // Presentation defines how the tool renders in @smoke-monkey/ui:
23  presentation: {
24    icon: '🚀',
25    label: 'Deploy Staging',
26    family: 'run',
27    tone: 'primary',
28  },
29  async execute(input, ctx) {
30    // 1. Validate arguments (model input is coerced, not schema-enforced)
31    const branch = typeof input.branch === 'string' ? input.branch.trim() : '';
32    if (!branch) {
33      return {
34        output: 'Error: branch parameter is required, e.g. branch="staging".',
35        isError: true, // Recoverable failure: loop demotes and retries
36      };
37    }
38
39    if (ctx.abortSignal.aborted) {
40      return { output: 'Deployment cancelled by user.', isError: true };
41    }
42
43    // 2. Stream real-time progress events to the UI
44    ctx.eventEmitter?.emit('tool.progress', {
45      toolCallId: ctx.toolCallId,
46      message: `Validating staging build for branch: ${branch}...`,
47    });
48
49    // 3. Execute external operation
50    const deployResult = await triggerStagingDeploy({ branch, dryRun: !!input.dryRun });
51
52    // 4. Return results: output for the LLM, data for the React UI
53    return {
54      success: true,
55      output: `Successfully deployed ${branch} to staging (URL: ${deployResult.url})`,
56      summary: `Deployed ${branch} to ${deployResult.url}`,
57      data: {
58        url: deployResult.url,
59        deploymentId: deployResult.id,
60        durationMs: deployResult.durationMs,
61      }, // Rides SSE events to @smoke-monkey/ui (never consumed by LLM)
62    };
63  },
64};

1import { createAgent } from '@smoke-monkey/harness';
2import { deployStagingTool } from './tools/deploy-staging';
3import { queryDatabaseTool } from './tools/query-db';
4
5// Register built-in tool groups alongside your custom tools
6const agent = createAgent({
7  workspacePath: process.cwd(),
8  provider: 'nvidia',
9  model: 'nvidia/nemotron-3-super-120b-a12b',
10  // Mix built-in groups ('filesystem', 'terminal', 'git', 'search') with custom tools:
11  tools: [
12    'filesystem',
13    'terminal',
14    'git',
15    deployStagingTool,
16    queryDatabaseTool,
17  ],
18  // Human-in-the-Loop permission policy
19  permission: async (req) => {
20    // Non-destructive tools auto-pass; destructiveHint triggers this check
21    if (req.tool === 'deploy_staging') {
22      return 'ask'; // Pauses the loop until user approves in the UI
23    }
24    return 'allow';
25  },
26});

1// Frontend: Next.js or React page using @smoke-monkey/ui
2import { ChatCanvas, ToolCard, useAgentStream } from '@smoke-monkey/ui';
3import '@smoke-monkey/ui/dist/styles.css';
4
5export default function AgentWorkbenchPage() {
6  // Connects via Server-Sent Events (SSE) to the backend agent runner
7  const { messages, events, sendPrompt, approvePermission } = useAgentStream({
8    endpoint: '/api/agent/stream',
9    permissionEndpoint: '/api/agent/permission',
10  });
11
12  return (
13    <div className="h-screen w-full bg-[#07090e]">
14      <ChatCanvas
15        messages={messages}
16        events={events}
17        onSend={sendPrompt}
18        // Custom tool card renderer for custom tools like deploy_staging:
19        renderCustomTool={(event) => {
20          if (event.toolName === 'deploy_staging') {
21            return (
22              <div className="p-4 rounded-xl bg-[#0d121c] border border-cyan-500/30 space-y-2">
23                <div className="flex items-center justify-between text-xs font-mono">
24                  <span className="text-cyan-400 font-bold">🚀 STAGING DEPLOYMENT</span>
25                  <span className="text-emerald-400">STATUS: {event.status}</span>
26                </div>
27                {event.data?.url && (
28                  <a
29                    href={event.data.url}
30                    target="_blank"
31                    rel="noreferrer"
32                    className="text-xs text-mono-300 underline block"
33                  >
34                    View Live Preview: {event.data.url}
35                  </a>
36                )}
37              </div>
38            );
39          }
40          return null; // Fallback to native Smoke Monkey ToolCard
41        }}
42        // Interactive Human-in-the-Loop permission dialog
43        onApprovePermission={approvePermission}
44      />
45    </div>
46  );
47}