@percival-labs/agent-social

Stateful social engagement toolkit for AI agents. Built because we shipped broken tooling and decided to fix it properly.

npm install @percival-labs/agent-social

Why This Exists

We built engagement tools for Clawstr (Nostr) and Moltbook from scratch. They had fundamental problems:

Problem	Impact	Fix
Timestamps showed time without date	Couldn't tell today from last week	ISO 8601 everywhere
Every scan returned full history	Reported old events as new	Cursor-based scanning
No dedup against what we'd already seen	Wasted time on stale data	State store with seen event tracking
Moltbook verification checked wrong path	Threaded replies stayed "pending" forever	Handle both response shapes
Challenge solver couldn't parse split words	"for ty" (forty) failed verification	Fragment merging parser
Duplicate posts from retry logic	Same comment posted 4 times	Content-hash idempotent publishing
Dead relays stayed in rotation	Timeouts on every scan	Relay health tracking with cooldown

We're the team building Vouch — trust infrastructure for AI agents. If we can't trust our own tooling, that's a problem. So we fixed it and open-sourced the result.

Quick Start

Nostr (Clawstr)

import { NostrAdapter, StateStore, statefulScan, idempotentPublish } from '@percival-labs/agent-social';

const store = new StateStore('.agent-social/state.json');

const nostr = new NostrAdapter({
  relays: [
    'wss://relay.damus.io',
    'wss://nos.lol',
    'wss://relay.primal.net',
  ],
  nsec: process.env.VOUCH_NSEC!,
}, store);

await nostr.connect();

// Scan for new replies — only events since last check
const result = await statefulScan({ adapter: nostr, stateStore: store });
console.log(`${result.meta.new} new events (${result.meta.total} total on relays)`);

for (const event of result.events) {
  // Every event has a full ISO 8601 timestamp — never just "8:48 AM"
  console.log(`[${event.timestamp}] ${event.author.slice(0, 8)}: ${event.content.slice(0, 100)}`);
}

// Publish — idempotent, won't double-post
const pub = await idempotentPublish(
  { adapter: nostr, stateStore: store },
  { content: 'Trust is earned, not given.', channel: 'vouch' },
);

if (pub.deduplicated) {
  console.log('Already posted this — skipped');
} else {
  console.log(`Posted: ${pub.id}`);
}

await nostr.disconnect();

Moltbook

import { MoltbookAdapter, StateStore, statefulScan, idempotentPublish } from '@percival-labs/agent-social';

const store = new StateStore('.agent-social/state.json');

const moltbook = new MoltbookAdapter({
  apiKey: process.env.MOLTBOOK_API_KEY!,
  proxyUrl: 'http://localhost:9111', // Optional: route through sanitizing proxy
}, store);

// Scan for new activity
const result = await statefulScan({ adapter: moltbook, stateStore: store });

// Publish a reply — handles verification challenges automatically
// If challenge has split words like "for ty" (forty), the parser handles it
// If the comment is already created, it verifies without re-posting (no duplicates)
const pub = await idempotentPublish(
  { adapter: moltbook, stateStore: store },
  {
    content: 'Interesting point about cold-start trust scoring.',
    replyTo: 'post-id-123',
    channel: 'ai-agents',
  },
);

Core Concepts

Stateful Scanning

Every scan uses a cursor to only fetch events since the last check. Events are tracked by ID — if you've seen it before, it won't appear in results.

// First scan: gets everything, sets cursor
const first = await statefulScan({ adapter, stateStore: store });
// first.meta.total = 150, first.meta.new = 150

// Second scan: only new events since cursor
const second = await statefulScan({ adapter, stateStore: store });
// second.meta.total = 3, second.meta.new = 3

Idempotent Publishing

Content is SHA-256 hashed before publishing. If the same content was already posted, the publish is skipped.

const pub1 = await idempotentPublish(config, { content: 'Hello world' });
// pub1.deduplicated = false (posted)

const pub2 = await idempotentPublish(config, { content: 'Hello world' });
// pub2.deduplicated = true (skipped — same content hash)

const pub3 = await idempotentPublish(config, { content: '  HELLO WORLD  ' });
// pub3.deduplicated = true (normalization: trim + lowercase + collapse spaces)

Relay Health

Nostr relays are tracked for success/failure. After 3 consecutive failures, a relay enters 30-minute cooldown and is skipped.

// relay.nostr.band times out 3 times → automatically skipped
// Other relays continue working
// After 30 minutes, it's retried
// One success resets the failure counter

Moltbook Verification

Moltbook returns verification challenges in two different shapes. This toolkit handles both:

// Shape A (top-level): { verification_code: "abc", challenge_text: "..." }
// Shape B (nested):    { comment: { verification: { verification_code: "abc", challenge_text: "..." } } }

// The adapter handles both automatically — you never need to think about it

The challenge solver handles obfuscated word problems:

import { parseChallenge } from '@percival-labs/agent-social';

// Split words
parseChallenge('A bot has for ty points. It gains six teen. Total?');
// → { numbers: [40, 16], operation: 'add', answer: 56 }

// Randomized case
parseChallenge('A node has fOr Ty connections.');
// → { numbers: [40], ... }

// Bracket decorators
parseChallenge('Score is [f]o[r] t{y} points.');
// → { numbers: [40], ... }

CLI

# Show engagement state
agent-social status

# Show relay health
agent-social health

# Import legacy engagement log
agent-social migrate ./engagement-log.json

State File

All state is stored in a single JSON file (default: .agent-social/state.json):

• Cursors — per-platform "last checked at" timestamps
• Seen event IDs — dedup cache (auto-pruned at 10K entries)
• Published content hashes — prevents duplicate posts
• Relay health — success/failure counts, cooldown timestamps
• Engagement log — append-only record of all actions

The state file is human-readable. You can inspect it, back it up, or reset it by deleting it.

API Reference

Core

Export	Description
StateStore	File-backed engagement state
statefulScan()	Cursor-based scan with dedup
idempotentPublish()	Content-hash dedup publishing
contentHash()	SHA-256 of normalized content
fromUnixSeconds()	Unix epoch → ISO 8601
toUnixSeconds()	ISO 8601 → Unix epoch
now()	Current time as ISO 8601
formatAge()	"3h ago (2026-03-08T12:00:00Z)"

Nostr

Export	Description
NostrAdapter	PlatformAdapter for Nostr relays
RelayPool	Connection-reusing relay pool with health tracking

Moltbook

Export	Description
MoltbookAdapter	PlatformAdapter for Moltbook API
parseChallenge()	Robust word problem solver
extractChallenge()	Extract verification from any response shape
isVerified()	Check if response indicates verification complete
sanitize()	Strip prompt injection patterns
sanitizeDeep()	Recursive sanitization for objects

What We Learned

1. Timestamps without dates are useless. toLocaleTimeString() outputs "8:48 AM" — which day? We reported week-old events as breaking news.

2. State is not optional. Without cursors and dedup, every scan returns the full history. Your agent re-processes everything, wastes tokens, and creates duplicate responses.

3. Test the exact failure modes. Our Moltbook verification worked for top-level posts but silently failed for threaded replies because the response shape was different. We didn't have a test for the nested shape.

4. Shallow copies mutate shared state. { ...EMPTY_STATE } looks like a fresh copy but shares inner objects. One instance modifying cursors corrupted every other instance. Classic JavaScript footgun.

5. Dead relays waste everyone's time. relay.nostr.band timed out consistently but stayed in rotation. Every scan waited 10 seconds for nothing. Track health, skip failures, retry later.

License

MIT — Percival Labs

Built because we believe broken tooling shouldn't be a secret. If your agent engagement tools have similar problems, use this or steal the patterns. That's why it's open source.