Corebot

Lightweight but capable TypeScript bot architecture. Single-process by default, tool- and skill-driven, MCP-ready, and safe-by-default.

Reliability Positioning

Corebot is optimized for the single-host reliable AI bot track:

one process, one local SQLite, one workspace
durable queue + retries + dead-letter replay
idempotent publish and inbound execution ledger
restart-safe recovery for stale in-flight work
observability and audit trail built into runtime

If your target is: "a bot that keeps running correctly on one machine under real failures", this repo is designed for that.

Delivery Semantics (What Is Guaranteed)

Scenario	Semantics	Mechanism
Inbound/outbound enqueue	At-least-once enqueue attempt	Durable `message_queue` + retry
Duplicate publish (same message id)	Deduplicated enqueue	`message_dedupe` unique key
Inbound re-processing after crash	Effectively-once runtime side effect	`inbound_executions` ledger + deterministic outbound id
Tool execution retries	At-least-once execution attempt	Bus retry / dead-letter policy
Scheduled task dispatch	At-least-once dispatch attempt	Scheduler emits synthetic inbound + retry path
Heartbeat alerts	Suppressed if pure ACK / recent duplicate	`ackToken` gate + delivery dedupe window

Notes:

"Effectively-once" here means duplicate deliveries are neutralized by idempotency guards inside Corebot; external side effects still need idempotent tool design.
Queue dead-letter is an explicit stop condition, not silent drop.

Failure Model and Recovery

Corebot handles the following failure classes by default:

Process crash during message handling Result: stale processing messages are recovered on restart and re-queued.
LLM/tool transient failure Result: exponential retry until maxAttempts, then dead-letter with error reason.
Duplicate inbound/outbound publish Result: dedupe key collapses duplicates to one queue record.
Router crash after runtime completed Result: inbound ledger serves cached result; runtime/tools are not re-executed.
Queue overload Result: overload backoff and configurable queue caps; overflow goes to dead-letter.
Schema migration failure Result: startup stops and reports pre-migration backup path for restore.

Production Baseline (Single Host)

Use this as the minimum reliable baseline:

{
  "storeFullMessages": true,
  "bus": {
    "maxAttempts": 5,
    "processingTimeoutMs": 120000,
    "maxPendingInbound": 5000,
    "maxPendingOutbound": 5000
  },
  "observability": {
    "enabled": true,
    "http": { "enabled": true, "host": "127.0.0.1", "port": 3210 }
  },
  "slo": {
    "enabled": true
  }
}

Also recommended:

persist both data/ and workspace/
enable webhook auth if webhook channel is exposed
set COREBOT_MCP_ALLOWED_SERVERS / COREBOT_MCP_ALLOWED_TOOLS in production

Features

Agent runtime with tool-calling loop
Built-in tools (fs, shell, web, memory, messaging, tasks, skills)
Skills via SKILL.md (progressive loading)
MCP client integration (tools injected dynamically)
SQLite storage for chats, messages, summaries, and tasks
Scheduler with cron | interval | once
Agent heartbeat loop with debounce wake, ack suppression, and duplicate-delivery guard
CLI channel for local usage (other channels stubbed)
Isolated tool runtime for high-risk tools (shell.exec, web.fetch, fs.write)
Durable queue with idempotent publish (retry/dead-letter/replay + dedupe by message id)
Inbound execution ledger to avoid duplicate runtime/tool execution on re-queued messages
Queue backpressure + per-chat rate limit (overflow to DLQ + overload backoff)
Observability endpoints (/health/*, /metrics, /status) and SLO monitor
Webhook channel (inbound POST + outbound pull API + optional token auth)
Migration safety with pre-migration backups and migration history
Persistent audit events for tool execution, denials, and errors

CLI and SDK

CLI: corebot (or pnpm run dev / pnpm run start)
SDK: import from @corebot/core and manage lifecycle via createCorebotApp()
CLI flags: corebot --help, corebot --version, corebot preflight

import { createCorebotApp, loadConfig } from "@corebot/core";

const app = await createCorebotApp({ config: loadConfig() });
await app.start();
// ...
await app.stop();

Quick Start

pnpm install --frozen-lockfile
export OPENAI_API_KEY=YOUR_KEY
pnpm run dev

Type in the CLI prompt to chat. Use /exit to quit.

Package Manager and Lockfile Policy

Use pnpm only (packageManager is pinned in package.json).
Commit both pnpm-lock.yaml and pnpm-workspace.yaml.
Install with pnpm install --frozen-lockfile in local reproducible runs, CI, and Docker.
Keep build-script approvals explicit in pnpm-workspace.yaml (onlyBuiltDependencies).
If a newly added dependency needs lifecycle scripts, run pnpm approve-builds and commit the updated policy file.

Example Commands

# Build + run production bundle locally
pnpm run build
node dist/bin.js

# Use a custom workspace/data directory
COREBOT_WORKSPACE=./workspace COREBOT_DATA_DIR=./data pnpm run dev

# Enable shell tool with executable allowlist
COREBOT_ALLOW_SHELL=true COREBOT_SHELL_ALLOWLIST="ls,git" pnpm run dev

# Enable web.search (Brave Search API)
BRAVE_API_KEY=YOUR_KEY COREBOT_ALLOWED_ENV=BRAVE_API_KEY pnpm run dev

# Restrict web.fetch to specific hosts/domains
COREBOT_WEB_ALLOWLIST="example.com,api.example.com" pnpm run dev

# Restrict web.fetch ports
COREBOT_WEB_ALLOWED_PORTS="443,8443" COREBOT_WEB_BLOCKED_PORTS="8080" pnpm run dev

# Isolate multiple high-risk tools in worker process
COREBOT_ISOLATION_TOOLS="shell.exec,web.fetch,fs.write" pnpm run dev

# Enable observability HTTP endpoints
COREBOT_OBS_HTTP_ENABLED=true COREBOT_OBS_HTTP_PORT=3210 pnpm run dev

# Enable webhook channel
COREBOT_WEBHOOK_ENABLED=true COREBOT_WEBHOOK_AUTH_TOKEN=YOUR_TOKEN pnpm run dev

# Manual database backup / restore
pnpm run ops:db:backup -- --db data/bot.sqlite
pnpm run ops:db:restore -- --db data/bot.sqlite --from data/backups/manual-xxxx.sqlite --force

# Validate startup config and MCP file before deployment
corebot preflight
corebot preflight --mcp-config ./path/to/.mcp.json

CLI queue ops:

/dlq list [inbound|outbound|all] [limit]
/dlq replay <queueId|inbound|outbound|all> [limit]

Example prompts (in CLI):

“Schedule a daily summary at 9am.”
“Save a short memory about my preferences.”
“List available skills.”

Configuration

You can configure via config.json or environment variables.

config.json (example)

{
  "workspaceDir": "workspace",
  "dataDir": "data",
  "sqlitePath": "data/bot.sqlite",
  "logLevel": "info",
  "provider": {
    "type": "openai",
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4o-mini",
    "temperature": 0.2,
    "timeoutMs": 60000,
    "maxInputTokens": 128000,
    "reserveOutputTokens": 4096
  },
  "historyMaxMessages": 30,
  "storeFullMessages": false,
  "maxToolIterations": 8,
  "maxToolOutputChars": 50000,
  "skillsDir": "workspace/skills",
  "mcpConfigPath": ".mcp.json",
  "mcpSync": {
    "failureBackoffBaseMs": 1000,
    "failureBackoffMaxMs": 60000,
    "openCircuitAfterFailures": 5,
    "circuitResetMs": 30000
  },
  "heartbeat": {
    "enabled": false,
    "intervalMs": 300000,
    "wakeDebounceMs": 250,
    "wakeRetryMs": 1000,
    "promptPath": "HEARTBEAT.md",
    "activeHours": "",
    "skipWhenInboundBusy": true,
    "ackToken": "HEARTBEAT_OK",
    "suppressAck": true,
    "dedupeWindowMs": 86400000,
    "maxDispatchPerRun": 20
  },
  "scheduler": { "tickMs": 60000 },
  "bus": {
    "pollMs": 1000,
    "batchSize": 50,
    "maxAttempts": 5,
    "retryBackoffMs": 1000,
    "maxRetryBackoffMs": 60000,
    "processingTimeoutMs": 120000,
    "maxPendingInbound": 5000,
    "maxPendingOutbound": 5000,
    "overloadPendingThreshold": 2000,
    "overloadBackoffMs": 500,
    "perChatRateLimitWindowMs": 60000,
    "perChatRateLimitMax": 120
  },
  "observability": {
    "enabled": true,
    "reportIntervalMs": 30000,
    "http": { "enabled": true, "host": "127.0.0.1", "port": 3210 }
  },
  "slo": {
    "enabled": true,
    "alertCooldownMs": 60000,
    "maxPendingQueue": 2000,
    "maxDeadLetterQueue": 20,
    "maxToolFailureRate": 0.2,
    "maxSchedulerDelayMs": 60000,
    "maxMcpFailureRate": 0.3
  },
  "isolation": {
    "enabled": true,
    "toolNames": ["shell.exec"],
    "workerTimeoutMs": 30000,
    "maxWorkerOutputChars": 250000,
    "maxConcurrentWorkers": 4,
    "openCircuitAfterFailures": 5,
    "circuitResetMs": 30000
  },
  "allowShell": false,
  "allowedShellCommands": [],
  "allowedEnv": [],
  "allowedWebDomains": [],
  "allowedWebPorts": [],
  "blockedWebPorts": [],
  "allowedMcpServers": [],
  "allowedMcpTools": [],
  "adminBootstrapKey": "",
  "adminBootstrapSingleUse": true,
  "adminBootstrapMaxAttempts": 5,
  "adminBootstrapLockoutMinutes": 15,
  "webhook": {
    "enabled": false,
    "host": "0.0.0.0",
    "port": 8788,
    "path": "/webhook",
    "authToken": "",
    "maxBodyBytes": 1000000
  },
  "cli": { "enabled": true }
}

Environment variables

OPENAI_API_KEY
OPENAI_BASE_URL
OPENAI_MODEL
OPENAI_TEMPERATURE
OPENAI_TIMEOUT_MS (deprecated alias for COREBOT_PROVIDER_TIMEOUT_MS)
COREBOT_PROVIDER_TIMEOUT_MS
COREBOT_PROVIDER_MAX_INPUT_TOKENS
COREBOT_PROVIDER_RESERVE_OUTPUT_TOKENS
COREBOT_WORKSPACE
COREBOT_DATA_DIR
COREBOT_SQLITE_PATH
COREBOT_LOG_LEVEL
COREBOT_HISTORY_MAX
COREBOT_STORE_FULL
COREBOT_MAX_TOOL_ITER
COREBOT_MAX_TOOL_OUTPUT
COREBOT_SKILLS_DIR
COREBOT_MCP_CONFIG
COREBOT_MCP_SYNC_BACKOFF_BASE_MS
COREBOT_MCP_SYNC_BACKOFF_MAX_MS
COREBOT_MCP_SYNC_OPEN_CIRCUIT_AFTER_FAILURES
COREBOT_MCP_SYNC_CIRCUIT_RESET_MS
COREBOT_HEARTBEAT_ENABLED
COREBOT_HEARTBEAT_INTERVAL_MS
COREBOT_HEARTBEAT_WAKE_DEBOUNCE_MS
COREBOT_HEARTBEAT_WAKE_RETRY_MS
COREBOT_HEARTBEAT_PROMPT_PATH
COREBOT_HEARTBEAT_ACTIVE_HOURS
COREBOT_HEARTBEAT_SKIP_WHEN_INBOUND_BUSY
COREBOT_HEARTBEAT_ACK_TOKEN
COREBOT_HEARTBEAT_SUPPRESS_ACK
COREBOT_HEARTBEAT_DEDUPE_WINDOW_MS
COREBOT_HEARTBEAT_MAX_DISPATCH_PER_RUN
COREBOT_ISOLATION_ENABLED
COREBOT_ISOLATION_TOOLS
COREBOT_ISOLATION_WORKER_TIMEOUT_MS
COREBOT_ISOLATION_MAX_WORKER_OUTPUT_CHARS
COREBOT_ISOLATION_MAX_CONCURRENT_WORKERS
COREBOT_ISOLATION_OPEN_CIRCUIT_AFTER_FAILURES
COREBOT_ISOLATION_CIRCUIT_RESET_MS
COREBOT_ALLOW_SHELL
COREBOT_SHELL_ALLOWLIST
COREBOT_ALLOWED_ENV
COREBOT_WEB_ALLOWLIST
COREBOT_WEB_ALLOWED_PORTS
COREBOT_WEB_BLOCKED_PORTS
COREBOT_BUS_POLL_MS
COREBOT_BUS_BATCH_SIZE
COREBOT_BUS_MAX_ATTEMPTS
COREBOT_BUS_RETRY_BACKOFF_MS
COREBOT_BUS_MAX_RETRY_BACKOFF_MS
COREBOT_BUS_PROCESSING_TIMEOUT_MS
COREBOT_BUS_MAX_PENDING_INBOUND
COREBOT_BUS_MAX_PENDING_OUTBOUND
COREBOT_BUS_OVERLOAD_PENDING_THRESHOLD
COREBOT_BUS_OVERLOAD_BACKOFF_MS
COREBOT_BUS_CHAT_RATE_WINDOW_MS
COREBOT_BUS_CHAT_RATE_MAX
COREBOT_OBS_ENABLED
COREBOT_OBS_REPORT_MS
COREBOT_OBS_HTTP_ENABLED
COREBOT_OBS_HTTP_HOST
COREBOT_OBS_HTTP_PORT
COREBOT_SLO_ENABLED
COREBOT_SLO_ALERT_COOLDOWN_MS
COREBOT_SLO_MAX_PENDING_QUEUE
COREBOT_SLO_MAX_DEAD_LETTER_QUEUE
COREBOT_SLO_MAX_TOOL_FAILURE_RATE
COREBOT_SLO_MAX_SCHEDULER_DELAY_MS
COREBOT_SLO_MAX_MCP_FAILURE_RATE
COREBOT_SLO_ALERT_WEBHOOK_URL
COREBOT_MCP_ALLOWED_SERVERS
COREBOT_MCP_ALLOWED_TOOLS
COREBOT_ADMIN_BOOTSTRAP_KEY
COREBOT_ADMIN_BOOTSTRAP_SINGLE_USE
COREBOT_ADMIN_BOOTSTRAP_MAX_ATTEMPTS
COREBOT_ADMIN_BOOTSTRAP_LOCKOUT_MINUTES
COREBOT_WEBHOOK_ENABLED
COREBOT_WEBHOOK_HOST
COREBOT_WEBHOOK_PORT
COREBOT_WEBHOOK_PATH
COREBOT_WEBHOOK_AUTH_TOKEN
COREBOT_WEBHOOK_MAX_BODY_BYTES

Notes:

COREBOT_ALLOWED_ENV is used by tools that explicitly gate env access (for example web.search) and by isolated shell.exec workers.
COREBOT_SHELL_ALLOWLIST matches executable names (for example ls,git), not full command prefixes.
COREBOT_WEB_ALLOWLIST restricts web.fetch target hosts (exact host or subdomain match).
COREBOT_WEB_ALLOWED_PORTS and COREBOT_WEB_BLOCKED_PORTS provide port allow/deny controls for web.fetch.
COREBOT_ISOLATION_TOOLS defaults to shell.exec; add web.fetch and/or fs.write to isolate network and file-write execution as well.
COREBOT_ISOLATION_MAX_CONCURRENT_WORKERS caps simultaneous isolated workers (default 4).
COREBOT_ISOLATION_OPEN_CIRCUIT_AFTER_FAILURES and COREBOT_ISOLATION_CIRCUIT_RESET_MS control per-tool circuit breaker for repeated worker failures.
Default policy denies non-admin fs.write to protected paths (skills/, IDENTITY.md, TOOLS.md, USER.md, .mcp.json).
COREBOT_MCP_ALLOWED_SERVERS and COREBOT_MCP_ALLOWED_TOOLS act as allowlists when set; empty lists allow all discovered MCP servers/tools.
COREBOT_MCP_SYNC_* controls MCP auto-sync retry backoff and temporary circuit-open window after repeated failures.
COREBOT_PROVIDER_TIMEOUT_MS bounds each LLM request; timeout errors enter normal retry/dead-letter flow.
COREBOT_PROVIDER_MAX_INPUT_TOKENS and COREBOT_PROVIDER_RESERVE_OUTPUT_TOKENS enforce prompt budgeting before each LLM turn.
COREBOT_HEARTBEAT_ACTIVE_HOURS accepts HH:mm-HH:mm in local process time; empty means always active.
COREBOT_HEARTBEAT_PROMPT_PATH is resolved relative to workspaceDir and must be non-empty to dispatch heartbeat turns.
COREBOT_WEBHOOK_AUTH_TOKEN can be sent via Authorization: Bearer <token> or x-corebot-token.
COREBOT_ADMIN_BOOTSTRAP_SINGLE_USE=true invalidates bootstrap elevation after first successful use.
COREBOT_ADMIN_BOOTSTRAP_MAX_ATTEMPTS and COREBOT_ADMIN_BOOTSTRAP_LOCKOUT_MINUTES control invalid-key lockout policy.

Deployment Guide

Build

pnpm install --frozen-lockfile
pnpm run build

Run

export OPENAI_API_KEY=YOUR_KEY
node dist/bin.js
# Or directly: node dist/main.js

Persist data
Ensure data/ and workspace/ are persisted (bind mount or volume). Corebot auto-creates them if missing.
Config
Use config.json for stable configuration in production; use env vars for secrets.

Docker

Build and run using the included Dockerfile:

docker build -t corebot .
docker run -it --rm \\
  -e OPENAI_API_KEY=YOUR_KEY \\
  -v $(pwd)/data:/app/data \\
  -v $(pwd)/workspace:/app/workspace \\
  corebot

Optional: mount .mcp.json or config.json if you want MCP or custom settings:

docker run -it --rm \\
  -e OPENAI_API_KEY=YOUR_KEY \\
  -v $(pwd)/data:/app/data \\
  -v $(pwd)/workspace:/app/workspace \\
  -v $(pwd)/.mcp.json:/app/.mcp.json \\
  -v $(pwd)/config.json:/app/config.json \\
  corebot

CI Template (GitHub Actions)

name: ci
on:
  push:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm run build

Built-in Tools

fs.read, fs.write, fs.list
shell.exec (disabled by default)
web.fetch, web.search (Brave Search API)
memory.read, memory.write
message.send, chat.register, chat.set_role
tasks.schedule, tasks.list, tasks.update
skills.list, skills.read, skills.enable, skills.disable, skills.enabled
heartbeat.status, heartbeat.trigger, heartbeat.enable (admin only)
mcp.reload (admin only; force refresh MCP config and tool bindings)
bus.dead_letter.list, bus.dead_letter.replay (admin only)

Tool API Reference

File System

Tool	Parameters	Description
`fs.read`	`path: string`	Read a text file within the workspace
`fs.write`	`path: string`, `content: string`, `mode?: "overwrite"\|"append"` (default `"overwrite"`)	Write a text file within the workspace
`fs.list`	`path?: string` (default `"."`)	List files in a workspace directory

Shell

Tool	Parameters	Description
`shell.exec`	`command: string`, `cwd?: string`, `timeoutMs?: number` (default 20000, max 120000)	Execute a command. Disabled by default; requires `allowShell=true`. Admin only.

Commands are tokenized and executed directly (no shell interpreter). If allowedShellCommands is non-empty, only listed executable names are permitted.

Web

Tool	Parameters	Description
`web.fetch`	`url: string`, `method?: "GET"\|"POST"` (default `"GET"`), `headers?: Record<string,string>`, `body?: string`, `timeoutMs?: number` (default 15000), `maxResponseChars?: number` (default 200000)	Fetch a URL over HTTP
`web.search`	`query: string`, `count?: number` (default 5, max 10)	Search the web using Brave Search API. Requires `BRAVE_API_KEY` in `allowedEnv`.

Memory

Tool	Parameters	Description
`memory.read`	`scope?: "global"\|"chat"\|"all"` (default `"all"`)	Read memory content
`memory.write`	`scope?: "global"\|"chat"` (default `"chat"`), `content: string`, `mode?: "append"\|"replace"` (default `"append"`)	Write memory. Global scope is admin only.

Memory files: workspace/memory/MEMORY.md (global), workspace/memory/{channel}_{chatId}.md (per-chat).

Messaging

Tool	Parameters	Description
`message.send`	`content: string`, `channel?: string`, `chatId?: string`	Send a message. Cross-chat sending is admin only.
`chat.register`	`channel?: string`, `chatId?: string`, `role?: "admin"\|"normal"`, `bootstrapKey?: string`	Register a chat for full message storage. See Admin Bootstrap below.
`chat.set_role`	`channel: string`, `chatId: string`, `role: "admin"\|"normal"`	Set chat role. Admin only.

Tasks

Tool	Parameters	Description
`tasks.schedule`	`prompt: string`, `scheduleType: "cron"\|"interval"\|"once"`, `scheduleValue: string`, `contextMode?: "group"\|"isolated"` (default `"group"`)	Create a scheduled task
`tasks.list`	`includeInactive?: boolean` (default `true`)	List tasks for this chat
`tasks.update`	`taskId: string`, `status?: "active"\|"paused"\|"done"`, `scheduleType?`, `scheduleValue?`, `contextMode?`	Update a task. Cross-chat updates are admin only.

scheduleValue format: cron expression for cron, milliseconds string for interval, ISO datetime for once.

Skills Management

Tool	Parameters	Description
`skills.list`	(none)	List available skills with enabled status
`skills.read`	`name: string`	Read a skill file content
`skills.enable`	`name: string`	Enable a skill for this chat
`skills.disable`	`name: string`	Disable a skill (always-skills cannot be disabled)
`skills.enabled`	(none)	List currently enabled skill names

Admin Tools

Tool	Parameters	Description
`heartbeat.status`	(none)	Show heartbeat runtime status, config, and next due chats. Admin only.
`heartbeat.trigger`	`reason?: string`, `force?: boolean`, `channel?: string`, `chatId?: string`	Queue an immediate heartbeat wake (optional force and target chat). Admin only.
`heartbeat.enable`	`enabled: boolean`, `reason?: string`	Enable/disable runtime heartbeat loop without restart. Admin only.
`mcp.reload`	`reason?: string`, `force?: boolean` (default `true`)	Reload MCP config and re-register tools. Set `force=false` to respect no-change checks and failure backoff. Admin only.
`bus.dead_letter.list`	`direction?: "inbound"\|"outbound"`, `limit?: number` (default 20)	List dead-letter queue entries. Admin only.
`bus.dead_letter.replay`	`queueId?: string`, `direction?: "inbound"\|"outbound"`, `limit?: number` (default 10)	Replay dead-letter entries back to pending. Admin only.

Security Model

Roles

Corebot uses two roles: admin and normal. New chats default to normal.

Admin Bootstrap

The first admin is created through a bootstrap flow:

Set COREBOT_ADMIN_BOOTSTRAP_KEY in config/env.
A user calls chat.register with role=admin and bootstrapKey=<the key>.
If the key matches, the chat is promoted to admin.
With adminBootstrapSingleUse=true (default), the key is invalidated after first use.
After adminBootstrapMaxAttempts (default 5) failed attempts, bootstrap locks for adminBootstrapLockoutMinutes (default 15).
Once an admin exists, new admins can only be granted by existing admins via chat.set_role.

Permission Matrix

Capability	Normal	Admin
File read/write/list (within workspace)	Yes	Yes
File write to protected paths	No	Yes
Shell execution	No	Yes
Web fetch (policy-restricted)	Yes	Yes
Memory write (chat scope)	Yes	Yes
Memory write (global scope)	No	Yes
Send message (same chat)	Yes	Yes
Send message (cross-chat)	No	Yes
Register own chat	Yes	Yes
Register other chats	No	Yes
Update own tasks	Yes	Yes
Update other chats' tasks	No	Yes
Heartbeat control/status tools	No	Yes
MCP tool execution	No	Yes
MCP reload	No	Yes
Dead-letter queue operations	No	Yes
Set chat roles	No	Yes

Protected Workspace Paths

Non-admin fs.write is denied for: IDENTITY.md, TOOLS.md, USER.md, .mcp.json, skills/ (and any path under it).

Memory

Corebot maintains two types of persistent memory:

Global memory (workspace/memory/MEMORY.md): shared across all chats. Admin-only for writes.
Per-chat memory (workspace/memory/{channel}_{chatId}.md): scoped to a specific chat session.

Both are automatically included in the system prompt when available, except isolated scheduled-task runs (chat memory excluded).

Conversation Compaction

When the stored message count for a chat exceeds historyMaxMessages * 2, Corebot automatically compacts:

Recent messages are sent to the LLM to generate a bullet summary (max 150 words).
Old messages beyond historyMaxMessages are pruned from storage.
The summary is stored in conversation_state and included in future system prompts.

This keeps context manageable while preserving key facts and decisions.

Inbound Execution Ledger

To ensure idempotency when messages are re-queued (e.g., after a retry), Corebot maintains an inbound_executions table:

Before processing, the router checks if the inbound message was already processed.
If completed, the cached response is reused without re-running the LLM or tools.
If a previous run is stale (older than bus.processingTimeoutMs), it is reclaimed.
Outbound message IDs are deterministic (outbound:{channel}:{chatId}:{inboundId}), so re-processing does not create duplicate replies.

Skills

Skills live in workspace/skills/<skill-name>/SKILL.md and support frontmatter:

---
name: web-research
description: "Web search + citation formatting"
always: false
requires:
  - env: ["BRAVE_API_KEY"]
tools:
  - web.search
  - web.fetch
---

# Web Research Skill

...

New skill directories/files are discovered dynamically during message handling, so adding a skill does not require a process restart.

MCP Integration

Create .mcp.json in repo root:

{
  "servers": {
    "myserver": {
      "command": "npx",
      "args": ["@example/mcp-server"]
    }
  }
}

MCP tools are injected as: mcp__<server>__<tool>.

.mcp.json is checked and auto-synced during message handling; changes are applied without restart.
You can also force refresh manually with mcp.reload. If .mcp.json is invalid (for example malformed JSON), reload is rejected and the previous MCP tool set remains active. Each enabled server must define exactly one of command or url; args/env are only valid with command. Use corebot preflight to validate config and .mcp.json before rolling out changes. Reload attempts are tracked in telemetry (corebot_mcp_reload_*) and persisted in audit_events with reason/duration metadata.

Agent Heartbeat

Heartbeat runs as a synthetic inbound turn per chat and reuses the same router/runtime/tool stack. It supports:

interval scheduling per chat
wake coalescing (debounce)
inbound-busy skip/retry gate
ack suppression (ackToken)
recent duplicate suppression (dedupeWindowMs)

Behavior controls live under heartbeat.* config and are also available via admin tools heartbeat.status, heartbeat.trigger, and heartbeat.enable.

Scheduler

Tasks support:

cron (cron expression)
interval (milliseconds)
once (ISO datetime)

Scheduler emits synthetic inbound messages with context_mode:

group: include chat context
isolated: minimal context

Reliability Metrics to Watch

For single-host reliability, track these first:

corebot_queue_pending{direction="inbound"}
corebot_queue_dead_letter{direction="inbound"}
corebot_tools_failure_rate
corebot_scheduler_max_delay_ms
corebot_mcp_failure_rate
corebot_heartbeat_scope_sent_total{scope="delivery"}
corebot_heartbeat_scope_skipped_total{scope="delivery"}

Fast interpretation:

rising inbound pending with flat throughput means handler bottleneck or provider slowdown
rising dead-letter means retries are exhausted and manual replay/recovery is needed
heartbeat sent drops to zero while skipped rises usually indicates ACK suppression or duplicate suppression dominating

Operations

Health endpoints:
- GET /health/live
- GET /health/ready
- GET /health/startup
Runtime endpoints:
- GET /metrics (Prometheus format)
- GET /status (JSON snapshot with queue/tool/scheduler/MCP health)
Webhook channel:
- POST <COREBOT_WEBHOOK_PATH> with JSON {chatId, content, senderId?, id?, createdAt?, metadata?}
- GET <COREBOT_WEBHOOK_PATH>/outbound?chatId=<id>&limit=<n>

Detailed incident and recovery procedures are documented in RUNBOOK.md.

Workspace Layout

workspace/
  IDENTITY.md
  USER.md
  TOOLS.md
  memory/
    MEMORY.md
  skills/
    <skill-name>/SKILL.md

Roadmap

WhatsApp / Telegram adapters
Container sandbox for tools
Additional provider adapters
Multi-instance coordination and queue partitioning

Inspiration

Corebot is inspired by NanoClaw + NanoBot patterns.

For the full architecture details, see ARCHITECTURE.md. For the operations runbook, see RUNBOOK.md. For contribution guidelines, see CONTRIBUTING.md.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github/workflows		.github/workflows
scripts		scripts
src		src
test		test
workspace		workspace
.dockerignore		.dockerignore
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
RUNBOOK.md		RUNBOOK.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

License

webllm/corebot

Folders and files

Latest commit

History

Repository files navigation

Corebot

Reliability Positioning

Delivery Semantics (What Is Guaranteed)

Failure Model and Recovery

Production Baseline (Single Host)

Features

CLI and SDK

Quick Start

Package Manager and Lockfile Policy

Example Commands

Configuration

config.json (example)

Environment variables

Deployment Guide

Docker

CI Template (GitHub Actions)

Built-in Tools

Tool API Reference

File System

Shell

Web

Memory

Messaging

Tasks

Skills Management

Admin Tools

Security Model

Roles

Admin Bootstrap

Permission Matrix

Protected Workspace Paths

Memory

Conversation Compaction

Inbound Execution Ledger

Skills

MCP Integration

Agent Heartbeat

Scheduler

Reliability Metrics to Watch

Operations

Workspace Layout

Roadmap

Inspiration

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

Packages