dingdawg-loop

DingDawg Loop Protocol (DDLP) — a framework for safe, scheduled, proactive AI agents with built-in governance gates. Agents declare what they WILL do, pass a governance check, and only then execute. If governance denies or errors, the loop skips that cycle. Fail-closed by default — no silent autonomous action.

Why DDLP Matters

AI agents running on a schedule without governance is a liability. An agent that sends emails every hour, syncs data nightly, or processes payments weekly needs a gate between "I want to act" and "I acted." DDLP puts that gate in place: every scheduled execution is governed, audited, and reversible. Proactive agents become safe by default.

Quick Start

Install

# Add to Claude Code
claude mcp add dingdawg-loop npx dingdawg-loop

# Or run directly
npx dingdawg-loop

1. Register a loop

{
  "tool": "register_loop",
  "arguments": {
    "name": "daily-report-sender",
    "schedule": "0 9 * * *",
    "action_type": "generate_report",
    "risk_tier": "low",
    "description": "Generate and save a daily analytics summary report to the reports directory every morning at 9am."
  }
}

Returns a loop_id you use for all subsequent operations.

2. Execute the loop (governance gate runs automatically)

{
  "tool": "execute_loop",
  "arguments": {
    "loop_id": "loop_abc123",
    "execution_notes": "Manual trigger for Monday report"
  }
}

The governance gate evaluates the loop's action type, description, and risk tier. Three possible outcomes:

• allow — loop executes, receipt recorded
• deny — loop blocked, violations listed, nothing executes
• review — loop queued for human approval, nothing executes until approved

3. Audit execution history

{
  "tool": "loop_audit",
  "arguments": {
    "loop_id": "loop_abc123",
    "limit": 10
  }
}

Returns every execution with its governance decision, risk score, and outcome.

Tools

register_loop

Register a new scheduled agent loop.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | yes | Unique human-readable name for this loop | | schedule | string | yes | Cron expression (0 9 * * *) or shorthand (@hourly, @daily) | | action_type | string | yes | What the loop does (send_email, generate_report, sync_data) | | risk_tier | enum | yes | low, medium, high, or critical | | description | string | yes | Detailed description (min 10 chars) — governance evaluates this | | metadata | object | no | Key-value pairs (owner, team, target_system) |

execute_loop

Manually trigger a loop. Governance gate runs BEFORE execution.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | loop_id | string | yes | The loop_id from register_loop | | execution_notes | string | no | Why this manual execution was triggered |

list_loops

List all registered loops with status and last execution.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | status_filter | enum | no | all, active, or paused (default: all) |

pause_loop

Pause a loop so it cannot be executed.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | loop_id | string | yes | The loop_id to pause | | reason | string | no | Why this loop is being paused |

resume_loop

Resume a paused loop.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | loop_id | string | yes | The loop_id to resume |

loop_audit

Get execution history and governance decisions for a loop.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | loop_id | string | yes | The loop_id to audit | | limit | number | no | Max records to return (default: 20) |

Safety Model

• Fail-closed: If the governance gate throws an error, the loop does NOT execute. Period.
• Governance receipt: Every execution (allowed, denied, or errored) gets a receipt with risk score and policy violations.
• Pause/resume: Loops can be safely paused without losing history.
• Audit trail: Every execution is persisted to ~/.dingdawg/loops/executions/ as JSON.
• No silent action: The loop protocol requires explicit execute_loop calls in v1. No background daemon.

Peer Dependency

DDLP requires dingdawg-governance as a peer dependency. In v1, the governance logic runs locally inside the loop server. In v2+, it will call the governance server directly via MCP-to-MCP transport.

npm install dingdawg-governance dingdawg-loop

Storage

Loop definitions and execution records are stored locally:

~/.dingdawg/loops/
  loop_abc123.json          # loop definition
  executions/
    exec_xyz789.json        # execution record with governance receipt

Roadmap

• v1 (current): Manual execution via execute_loop. Schedule stored but not auto-executed.
• v2: Background daemon that executes loops on their cron schedule, with governance gate on every tick.
• v3: Cloud API integration — governance decisions from DingDawg cloud, centralized audit trail.

License

MIT