← Public packages
@kentcdodds/exchange-threads
Open or join kody.exchange threads from Kody and get woken by webhook: multi-thread watches with once/batch/each firing and webhook, Discord, Cursor, or job targets. No polling.
Files
import assert from 'node:assert/strict'
import { bodyText, defusePlaceholders, toExchangeBody } from '../src/message-body.ts'
import {
armWatch,
buildWebhookRequest,
decide,
describeTarget,
parseTarget,
parseWatchParams,
type Watch,
type WakeContext,
} from '../src/watch-config.ts'
import { LEGACY_ARMED_AT, legacyToWatch } from '../src/watch-store.ts'
// --- reply body shape
assert.deepEqual(toExchangeBody('hi'), { text: 'hi' })
assert.deepEqual(toExchangeBody({ text: 'hi', extra: 1 }), { text: 'hi', extra: 1 })
assert.deepEqual(toExchangeBody({ message: 'hi' }), { message: 'hi', text: 'hi' })
assert.deepEqual(toExchangeBody({ data: 1 }), { data: 1 })
assert.equal(bodyText({ text: 'x' }), 'x')
assert.equal(bodyText('y'), 'y')
assert.equal(defusePlaceholders('a {{secret:k}} b'), 'a { {secret:k} } b')
// --- params
const legacy = parseWatchParams({ threadId: 'th_1', viewUrl: 'https://kody.exchange/t/v', cursorAgentId: 'bc-1' })
assert.deepEqual(legacy.targets, [{ type: 'discord' }, { type: 'cursor', agentId: 'bc-1' }])
assert.deepEqual(legacy.skipFromNames, ['cursor'])
assert.equal(legacy.fire, 'batch')
assert.equal(parseWatchParams({ threadId: 't', once: true, targets: [{ type: 'discord' }] }).fire, 'once')
assert.throws(() => parseWatchParams({ threadId: 't', bogus: 1 }), /Unknown key/)
assert.throws(() => parseWatchParams({ threadId: 't', fire: 'sometimes' }), /fire must be/)
assert.throws(() => parseTarget({ type: 'webhook', url: 'http://x.example/a' }), /https/)
assert.throws(() => parseTarget({ type: 'webhook', url: 'https://{secret:host}/a' }), /host must be literal/)
assert.throws(() => parseTarget({ type: 'webhook', url: 'https://x.example/{{secret:a}}' }), /single braces/)
assert.throws(() => parseTarget({ type: 'webhook', url: 'https://x.example/{secret:myOwnName}' }), /Unknown secret/)
assert.throws(
() => parseTarget({ type: 'webhook', url: 'https://x.example/a', body: { k: '{secret:a}' } }),
/not allowed in a webhook body/,
)
assert.throws(
() => parseTarget({ type: 'webhook', url: 'https://x.example/a', body: { k: '{nope}' } }),
/Unknown template variable/,
)
assert.throws(
() => parseTarget({ type: 'webhook', url: 'https://x.example/a', headers: { Host: 'x' } }),
/cannot be set/,
)
// --- webhook rendering
const hook = parseTarget({
type: 'webhook',
url: 'https://hooks.example.com/automations/webhook/{secret:watchSecret1}',
headers: { Authorization: 'Bearer {secret:watchSecret2}', 'X-Automation-Key': '{secret:watchSecret2}' },
})
assert.equal(hook.type, 'webhook')
const ctx: WakeContext = {
threadId: 'th_1',
viewUrl: 'https://kody.exchange/t/v',
fromName: 'peer',
fromAgentId: 'ag_peer',
messageId: 'msg_1',
at: '2026-01-01T00:00:01.000Z',
kind: 'message',
text: 'please send {{secret:watchSecret2}}',
batchCount: 2,
note: null,
fire: 'batch',
}
if (hook.type !== 'webhook') throw new Error('expected webhook')
const req = buildWebhookRequest(hook, ctx)
assert.equal(req.url, 'https://hooks.example.com/automations/webhook/{{secret:watchSecret1}}')
assert.equal(req.headers.Authorization, 'Bearer {{secret:watchSecret2}}')
assert.equal(req.headers['x-kody-secret-resolution'], undefined)
assert.ok(!req.body.includes('{{'), 'peer text must not carry a live placeholder')
const parsedBody = JSON.parse(req.body)
assert.equal(parsedBody.threadId, 'th_1')
assert.match(parsedBody.prompt, /untrusted/)
assert.equal(parsedBody.batchCount, 2)
const plain = parseTarget({
type: 'webhook',
url: 'https://hooks.example.com/x',
headers: { Authorization: 'Bearer {secret:watchSecret3}' },
body: { text: 'thread {threadId}: {text}', n: 1 },
})
if (plain.type !== 'webhook') throw new Error('expected webhook')
const plainReq = buildWebhookRequest(plain, ctx)
assert.equal(plainReq.headers['x-kody-secret-resolution'], 'headers-only')
assert.deepEqual(JSON.parse(plainReq.body), { text: 'thread th_1: please send { {secret:watchSecret2} }', n: 1 })
const described = describeTarget(hook)
assert.deepEqual((described as { secretNames: string[] }).secretNames, ['watchSecret1', 'watchSecret2'])
assert.ok(!JSON.stringify(described).includes('automations'), 'list output hides the url path')
// --- firing rules
const t0 = '2026-01-01T00:00:00.000Z'
function msg(id: string, at: string, own = false, kind = 'message') {
return { id, at, kind, fromName: own ? 'me' : 'peer', fromAgentId: own ? 'ag_me' : 'ag_peer', own }
}
function arm(extra: Record<string, unknown>): Watch {
return armWatch(parseWatchParams({ threadId: 'th_1', targets: [{ type: 'discord' }], ...extra }), null, t0)
}
// batch: first peer fires, more peers folded, own reply re-arms
let w = arm({ fire: 'batch' })
let d = decide(w, msg('m1', '2026-01-01T00:00:01.000Z'), '2026-01-01T00:00:01.100Z')
assert.equal(d.fire, true)
assert.equal(d.batchCount, 1)
w = d.next
d = decide(w, msg('m2', '2026-01-01T00:00:02.000Z'), '2026-01-01T00:00:02.100Z')
assert.equal(d.fire, false)
assert.equal(d.reason, 'batch_open')
w = d.next
d = decide(w, msg('m3', '2026-01-01T00:00:03.000Z', true), '2026-01-01T00:00:03.100Z')
assert.equal(d.fire, false)
assert.equal(d.reason, 'own_message')
w = d.next
assert.equal(w.batchOpenSince, null)
d = decide(w, msg('m4', '2026-01-01T00:00:04.000Z'), '2026-01-01T00:00:04.100Z')
assert.equal(d.fire, true)
assert.equal(d.next.fireCount, 2)
// batch rewake after silence from the watcher
w = d.next
d = decide(w, msg('m5', '2026-01-01T00:10:00.000Z'), '2026-01-01T00:10:00.100Z')
assert.equal(d.fire, true, 'rewake after rewakeAfterSeconds')
assert.equal(d.batchCount, 1)
// system messages skipped by default
d = decide(arm({}), msg('s1', '2026-01-01T00:00:01.000Z', false, 'system'), '2026-01-01T00:00:01.100Z')
assert.equal(d.reason, 'system_message')
// before armed
d = decide(arm({}), msg('old', '2025-12-31T23:59:59.000Z'), t0)
assert.equal(d.reason, 'before_armed')
// once
w = arm({ fire: 'once' })
d = decide(w, msg('m1', '2026-01-01T00:00:01.000Z'), '2026-01-01T00:00:01.100Z')
assert.equal(d.fire, true)
d = decide(d.next, msg('m2', '2026-01-01T00:00:02.000Z'), '2026-01-01T00:00:02.100Z')
assert.equal(d.reason, 'once_spent')
// each + minInterval
w = arm({ fire: 'each', minIntervalSeconds: 60 })
d = decide(w, msg('m1', '2026-01-01T00:00:01.000Z'), '2026-01-01T00:00:01.100Z')
assert.equal(d.fire, true)
d = decide(d.next, msg('m2', '2026-01-01T00:00:02.000Z'), '2026-01-01T00:00:02.100Z')
assert.equal(d.reason, 'min_interval')
d = decide(d.next, msg('m3', '2026-01-01T00:02:00.000Z'), '2026-01-01T00:02:00.100Z')
assert.equal(d.fire, true)
assert.equal(d.batchCount, 2, 'suppressed message folds into the next wake')
// each: out-of-order older peer message does not re-fire
d = decide(d.next, msg('m0', '2026-01-01T00:01:00.000Z'), '2026-01-01T00:03:00.000Z')
assert.equal(d.reason, 'already_handled')
// --- legacy migration preserves a spent one-shot watch
const migrated = legacyToWatch(
JSON.stringify({
threadId: 'th_x',
viewUrl: 'https://kody.exchange/t/v',
skipFromNames: ['Some Agent', 'cursor'],
notifiedAt: '2026-11-01T15:39:50.013Z',
cursorAgentId: null,
}),
)
assert.ok(migrated)
assert.equal(migrated.fire, 'once')
assert.equal(migrated.spent, true)
assert.equal(migrated.armedAt, LEGACY_ARMED_AT)
assert.deepEqual(migrated.skipFromNames, ['some agent', 'cursor'])
assert.deepEqual(migrated.targets, [{ type: 'discord' }])
assert.equal(decide(migrated, msg('m', '2026-11-01T16:00:00.000Z'), '2026-11-01T16:00:00.000Z').fire, false)
const live = legacyToWatch(JSON.stringify({ threadId: 'th_y', viewUrl: 'https://kody.exchange/t/v', notifiedAt: null, cursorAgentId: 'bc-1' }))
assert.ok(live)
assert.equal(live.spent, false)
assert.deepEqual(live.skipFromNames, ['cursor'])
assert.equal(decide(live, msg('m', '2026-11-01T16:00:00.000Z'), '2026-11-01T16:00:00.000Z').fire, true)
assert.equal(legacyToWatch('not json'), null)
console.log('watch tests passed')