Is Smoke Monkey an AI model?

No. Smoke Monkey is not an LLM. It is an embeddable, framework-agnostic runtime that turns LLMs (NVIDIA, Gemini, OpenAI, Claude, Ollama) into autonomous engineering agents capable of multi-step planning, calling tools, editing files, and running test loops with zero runtime dependencies.

Do I need a database (Postgres, SQLite, or Redis)?

No database is required. State is persisted through lean session files on disk, or you can plug in your own custom storage adapter. You can deploy it as a CLI, a desktop app, or inside a serverless function without provisioning a database.

How does human-in-the-loop permission gating work?

Smoke Monkey comes with three permission policies: allow-all, deny-all, and ask-default (or a custom function resolver). When a sensitive tool like edit_file or run_command is called under "ask", the runtime emits a permission.required event, pausing execution until your code or UI calls agent.resolvePermission(id, "allow" | "deny").

How does the Model Context Protocol (MCP) server work?

Smoke Monkey ships an official stdio MCP server in smoke-monkey-harness-mcp. Point Claude Code, Cursor, Codex, or opencode at it using npx -y smoke-monkey-harness-mcp to let other AI tools plan, scaffold, verify, and run agents using Smoke Monkey automatically.

What are SKILL.md skills and how do they prevent context bloat?

Skills are directories containing a SKILL.md workflow file. The system prompt only includes a one-line catalog of available skills. When a task requires specialized expertise (e.g. frontend-ui-engineering, test-driven-development, or security-hardening), the agent calls use_skill to load instructions just-in-time, saving thousands of tokens.

What is an AI Agent Harness?

An AI agent harness is the execution environment that bridges raw Large Language Models (LLMs) to real-world software engineering capabilities. While an LLM generates tokens, an AI harness manages deterministic phase loops (explore, plan, edit, verify, recover), tool execution sandboxing, token budget compaction, and safety gates needed for autonomous problem-solving.

What makes Smoke Monkey an Agentic AI runtime rather than a simple wrapper?

Unlike basic prompt-response chains, Smoke Monkey implements true agentic AI architecture: a deterministic 6-phase state machine with automatic failure recovery, runaway loop guards, 24 built-in developer tools, dynamic subcontext isolation, and interactive human-in-the-loop permission pauses.

Is Smoke Monkey Harness 100% Open Source AI?

Yes. Smoke Monkey Harness is 100% open source under the permissive MIT license with zero runtime dependencies. There is no telemetry lock-in, no mandatory cloud backend, and no database requirement—giving engineering teams complete sovereignty over their agent code.

What Agent APIs does Smoke Monkey Harness provide?

Smoke Monkey provides composable TypeScript Agent APIs: createAgent() for initialization, agent.run() for multi-turn execution, agent.on() for fine-grained lifecycle and streaming events, agent.resolvePermission() for interactive human authorization, subcontext switching APIs, and stdio Model Context Protocol (MCP) server endpoints.

Can I run completely offline without API keys?

Yes! Smoke Monkey natively supports Ollama out of the box. Set provider: "ollama" and model: "qwen3:8b" with workspacePath, and the agent will run locally on your machine with zero external network requests.

Human-in-the-Loop Safety

Permissions & The Three Pauses

Autonomous agents must never destroy code, wipe databases, or execute unauthorized terminal commands. Smoke Monkey introduces The Three Interactive Pauses: non-blocking suspension gates that freeze the loop without crashing the process.

The Three Interactive Pauses in Smoke Monkey: Tool Permission, Ask User, and MCP Server Approval — Figure 1: Interactive checkpoint gates suspending the autonomous agent loop awaiting developer confirmation.

Interactive Pause Protocol Flow

Explore how each pause gate suspends execution non-blockingly until developer confirmation:

Interactive Engine Flow

Drag nodes · Scroll to pan & zoom

🎯 User Prompt "Fix auth bug in auth.ts"

1. EXPLORE Inspect · Glob · Grep

2. PLAN Sub-tasks · JIT Skills

3. EDIT Line-level Patch

4. VERIFY Run Tests & Diff

5. COMPLETE Session Persist

🔁 RECOVER (Demotion Loop) Inspect stderr · Rollback · Auto-heal

🛡️ Automated Loop Guards (Max 1000 Steps · 3x Identical Error Abort · 90% Compaction)

Deterministic loop: verification failure triggers an automated recovery demotion instead of halting.

Live Diagram

The 3 Pause Gates Explained

1. Tool Permission Pause

Safety Gate

Triggered whenever the agent invokes mutating actions (write_file, edit_file, run_command, delete_file).

Suspends the loop. Read-only actions (read_file, glob, grep) execute immediately without prompting.

Resolution API:agent.resolvePermission(toolCallId, 'allow' | 'deny')

2. Clarification Pause

Human Feedback

Triggered when the agent calls the built-in ask_user tool to seek human input or clarify ambiguous instructions.

Freezes execution state and turns the chat composer into an active answer input.

Resolution API:agent.respond(toolCallId, userReplyString)

3. MCP Server Approval Pause

Access Policy

Triggered when the agent attempts to call a tool from an untrusted or disabled external MCP server.

Suspends execution until the server is explicitly vetted and enabled.

Resolution API:agent.resolveMcpDecision(toolCallId, { action: 'enable', names: [serverId] })

Wiring Pauses in TypeScript

Listen to pause events on the agent instance and resolve them over WebSockets, CLI prompts, or webhooks:

permissions-agent.tstypescript

1import { createAgent } from '@smoke-monkey/harness';
2
3const agent = createAgent({
4  workspacePath: process.cwd(),
5  autoApprove: false, // Enforce strict human verification
6});
7
8// 1. Tool Permission Pause
9agent.on('permission.required', async (e) => {
10  const { toolCallId, toolName, input } = e.data;
11  console.log(`Agent wants to execute: ${toolName}`);
12  
13  const approved = await showConfirmationModal(toolName, input);
14  await agent.resolvePermission(toolCallId, approved ? 'allow' : 'deny');
15});
16
17// 2. User Clarification Pause
18agent.on('ask_user.required', async (e) => {
19  const { toolCallId, question } = e.data;
20  const answer = await getUserPromptReply(question);
21  await agent.respond(toolCallId, answer);
22});
23
24// Run an autonomous coding task
25await agent.run('Refactor src/auth.ts to use argon2 instead of bcrypt');

Graceful Denial & Self-Healing

When a user clicks Deny, the harness does not crash. Instead, the rejection is cleanly passed back to the model as an error response (Permission denied by user), allowing the agent to formulate an alternate strategy without editing that file.

Explore External Tool Connectors

Learn how the Model Context Protocol (MCP) securely connects tools.