AgentPathfinder

Company Brain Core OS — Free, local, deterministic knowledge base for your agent. Start here before adding audit trails.

Your AI agent said "Done." Prove it. Cryptographically signed tool-level audit trails. See exactly which command failed, what the error was, and whether your agent lied about success.

Part of the CertainLogic Stack

This skill works standalone. Install it, sign your tool calls, get proof of execution.

Works even better with Company Brain Core OS (clawhub install company-brain-os):

• Brain stores your audit patterns and flags suspicious signatures
• CertainLogic Smart Router — routes audit queries to the right tier
• Skill Vetter Plus — verifies audit integrity before external review

All three are independent. Use Pathfinder alone when you need verifiable execution. Add Brain when you want smart correlation of audit events.

What This Is

The provenance layer for AI agent execution. Every tool call is cryptographically signed with HMAC-SHA256. Every failure is recorded. Every lie is detectable.

AgentPathfinder doesn't make your agent honest. It makes dishonesty proveable.

What You Get

Pro (coming soon): Multi-agent tracking, audit exports, webhooks. Enterprise: On-prem, SSO/SAML, hosted vault.

What This Is NOT

The Problem

Your AI agent says "Done" — but you have no idea what actually happened at the tool level.

• Silent failures: The agent claims success while docker push returned exit_code=1
• Missing steps: The agent skips pytest entirely and claims all tests passed
• Wrong commands: The agent runs echo "done" instead of the actual build
• Crash recovery: The agent restarts, has no memory of which tool calls were in-flight
• Multi-agent confusion: Two agents claim the same step — who actually did it?

You only find out when your customer does. 😤

Installation

clawhub install certainlogicai.agentpathfinder

Quick Start

# Create a signed task
python3 -m agentpathfinder create deploy "test,build,push,restart"
# → Task created: deploy-a7f3d2e1

# Start the audit chain for a step
# (automatically done when agent runs tools)

# View the live dashboard
cd ~/.openclaw/skills/certainlogicai.agentpathfinder
python3 scripts/dashboard_v130.py watch --task deploy-a7f3d2e1
# → Serves dashboard at http://localhost:8080
# → Auto-refreshes every 2 seconds
# → Shows tool call tree with args, results, HMAC signatures
# → Fraud alerts: hanging calls, false claims, missing results

# View audit trail
python3 -m agentpathfinder audit deploy-a7f3d2e1
# → Lists all signed tool events

# Export audit trail
python3 scripts/dashboard_v130.py export --task deploy-a7f3d2e1
# → Signed JSONL with every event + HMAC verification

SDK Usage

from agentpathfinder import TaskEngine
from agentpathfinder.tool_audit import ToolAuditChain, AuditedToolExecutor

# Initialize tool audit
task = TaskEngine(data_dir="~/.agentpathfinder")
step_list = [
    {"name": "test"},
    {"name": "build"},
    {"name": "push"},
    {"name": "restart"},
]
task_id = task.create_task("deploy", step_list)

# Start audit for a step
audit = task.get_tool_audit(task_id, step_number=1)

# Manually log a tool call
tool_id = audit.log_tool_call("exec", {"command": "pytest tests/ -v"})
# ... run the command ...
audit.log_tool_result(tool_id, result={"passed": True, "count": 17}, exit_code=0)
# → Logs TOOL_INVOKED with args + HMAC
# → Logs TOOL_RESULT with exit_code + output + HMAC

# Or use the executor wrapper (auto-logs real commands)
executor = AuditedToolExecutor(audit)
result = executor.exec("echo hello")  # Auto-logged

# Detect fraud
audit.detect_hanging_calls()  # Tools invoked but no result
audit.get_tool_summary()      # What was called, what failed

CLI Reference

python3 -m agentpathfinder create <name> <steps>       # Create task (comma-separated steps)
python3 -m agentpathfinder status <task_id>            # View task status
python3 -m agentpathfinder audit <task_id>             # Verify HMAC signatures
python3 -m agentpathfinder reset-step <task_id> <n>    # Reset step (signed action)

Dashboard

# Live watch mode with built-in HTTP server
python3 scripts/dashboard_v130.py watch --task <task_id>
# → http://localhost:8080

# Generate static report
python3 scripts/dashboard_v130.py generate --task <task_id>

# Export as JSON
python3 scripts/dashboard_v130.py export --task <task_id>

Dashboard shows:

• Tool call tree (args + results visible)
• HMAC signature for every event
• Integrity verification panel (tampered/corrupted count)
• Fraud alerts (hanging calls, false claims)
• Tool summary by category
• Multi-task support
• Dark mode with CertainLogic brand colors

Safety

Read SAFETY.md before using in production.

Key limitations:

• Agent with filesystem access can read vault shards — not a sandbox
• False completions get signed — system records claims, not truth
• No independent observer — agent controls both execution AND logging

License

MIT License © CertainLogic