truematch-plugin 0.1.0

package/dist/negotiation.js

@@ -0,0 +1,232 @@
+import { readFile, writeFile, mkdir, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { TRUEMATCH_DIR } from "./identity.js";
+import { publishMessage } from "./nostr.js";
+const THREADS_DIR = join(TRUEMATCH_DIR, "threads");
+// Per spec: threads with no response expire after 72 hours
+const THREAD_EXPIRY_MS = 72 * 60 * 60 * 1000;
+// Maximum active threads allowed from a single unknown peer pubkey.
+// Prevents disk exhaustion from arbitrary senders spamming new thread_ids.
+const MAX_INBOUND_THREADS_PER_PEER = 3;
+// Maximum rounds before hard termination
+export const MAX_ROUNDS = 10;
+async function ensureThreadsDir() {
+    if (!existsSync(THREADS_DIR)) {
+        await mkdir(THREADS_DIR, { recursive: true });
+    }
+}
+// UUID v4 pattern — all wire-supplied thread IDs must match before being used as filenames
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function threadFile(thread_id) {
+    if (!UUID_V4_RE.test(thread_id)) {
+        throw new Error(`Invalid thread_id format: ${thread_id}`);
+    }
+    return join(THREADS_DIR, `${thread_id}.json`);
+}
+export async function loadThread(thread_id) {
+    const path = threadFile(thread_id);
+    if (!existsSync(path))
+        return null;
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+}
+export async function saveThread(state) {
+    await ensureThreadsDir();
+    await writeFile(threadFile(state.thread_id), JSON.stringify(state, null, 2), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+export async function listActiveThreads() {
+    await ensureThreadsDir();
+    const files = await readdir(THREADS_DIR);
+    const threads = [];
+    for (const f of files) {
+        if (!f.endsWith(".json"))
+            continue;
+        try {
+            const raw = await readFile(join(THREADS_DIR, f), "utf8");
+            const t = JSON.parse(raw);
+            if (t.status === "in_progress")
+                threads.push(t);
+        }
+        catch {
+            // Skip corrupted thread files rather than aborting the entire listing
+        }
+    }
+    return threads;
+}
+// Expire threads that have been silent for > 72 hours
+export async function expireStaleThreads(nsec, relays) {
+    const active = await listActiveThreads();
+    for (const thread of active) {
+        if (Date.now() - new Date(thread.last_activity).getTime() >
+            THREAD_EXPIRY_MS) {
+            // Save before sending so a relay failure doesn't cause duplicate end messages on next cycle
+            thread.status = "expired";
+            thread.last_activity = new Date().toISOString();
+            await saveThread(thread);
+            await sendEnd(nsec, thread.peer_pubkey, thread.thread_id, relays);
+        }
+    }
+}
+// Create a new negotiation thread. Does NOT send an opening message —
+// Claude writes and sends the opening via `truematch match --send`.
+export async function initiateNegotiation(peerNpub) {
+    const thread_id = randomUUID();
+    const now = new Date().toISOString();
+    const state = {
+        thread_id,
+        peer_pubkey: peerNpub,
+        round_count: 0,
+        initiated_by_us: true,
+        we_proposed: false,
+        peer_proposed: false,
+        started_at: now,
+        last_activity: now,
+        status: "in_progress",
+        messages: [],
+    };
+    await saveThread(state);
+    return state;
+}
+// Save an incoming peer message to the thread
+export async function receiveMessage(thread_id, peerNpub, content, type) {
+    // Validate thread_id from wire — reject silently to avoid leaking thread existence
+    if (!UUID_V4_RE.test(thread_id))
+        return null;
+    await ensureThreadsDir();
+    const now = new Date().toISOString();
+    let state = await loadThread(thread_id);
+    if (!state) {
+        // First message from this peer on this thread_id.
+        // Guard against DoS: count existing active threads from this peer.
+        const existing = await listActiveThreads();
+        const peerThreadCount = existing.filter((t) => t.peer_pubkey === peerNpub && !t.initiated_by_us).length;
+        if (peerThreadCount >= MAX_INBOUND_THREADS_PER_PEER)
+            return null;
+        // Create a new inbound thread
+        state = {
+            thread_id,
+            peer_pubkey: peerNpub,
+            round_count: 0,
+            initiated_by_us: false,
+            we_proposed: false,
+            peer_proposed: false,
+            started_at: now,
+            last_activity: now,
+            status: "in_progress",
+            messages: [],
+        };
+    }
+    else if (peerNpub !== state.peer_pubkey) {
+        // Reject messages from a different sender — return null (not state) to avoid
+        // leaking thread existence or peer identity to the caller
+        return null;
+    }
+    state.last_activity = now;
+    // round_count tracks only our outgoing messages — do not increment on receive
+    const incoming = {
+        role: "peer",
+        content,
+        timestamp: now,
+    };
+    state.messages.push(incoming);
+    if (type === "end") {
+        state.status = "declined";
+    }
+    else if (type === "match_propose") {
+        state.peer_proposed = true;
+        try {
+            const narrative = JSON.parse(content);
+            state.match_narrative = narrative;
+        }
+        catch {
+            // content was plain text; peer_proposed is still recorded
+        }
+        // Double-lock: if we already sent a proposal, both sides have now proposed → match confirmed
+        if (state.we_proposed) {
+            state.status = "matched";
+        }
+    }
+    await saveThread(state);
+    return state;
+}
+// Send a free-form negotiation message
+export async function sendMessage(nsec, thread_id, content, relays) {
+    const state = await loadThread(thread_id);
+    if (!state)
+        throw new Error(`Thread ${thread_id} not found`);
+    if (state.status !== "in_progress") {
+        throw new Error(`Thread ${thread_id} is not in progress (status: ${state.status})`);
+    }
+    if (state.round_count >= MAX_ROUNDS) {
+        throw new Error(`Thread ${thread_id} has reached the ${MAX_ROUNDS}-round cap`);
+    }
+    const now = new Date().toISOString();
+    const msg = {
+        truematch: "2.0",
+        thread_id,
+        type: "negotiation",
+        timestamp: now,
+        content,
+    };
+    await publishMessage(nsec, state.peer_pubkey, msg, relays);
+    state.messages.push({ role: "us", content, timestamp: now });
+    state.round_count += 1;
+    state.last_activity = now;
+    await saveThread(state);
+}
+// Propose a match (double-lock: peer must also propose for match to confirm)
+export async function proposeMatch(nsec, thread_id, narrative, relays) {
+    const state = await loadThread(thread_id);
+    if (!state)
+        throw new Error(`Thread ${thread_id} not found`);
+    if (state.status !== "in_progress") {
+        throw new Error(`Thread ${thread_id} is not in progress (status: ${state.status})`);
+    }
+    if (state.we_proposed)
+        throw new Error(`Already proposed on thread ${thread_id}`);
+    const now = new Date().toISOString();
+    const content = JSON.stringify(narrative);
+    const msg = {
+        truematch: "2.0",
+        thread_id,
+        type: "match_propose",
+        timestamp: now,
+        content,
+    };
+    await publishMessage(nsec, state.peer_pubkey, msg, relays);
+    state.messages.push({ role: "us", content, timestamp: now });
+    state.round_count += 1;
+    state.last_activity = now;
+    state.we_proposed = true;
+    // If peer already proposed, the match is confirmed (double-lock cleared)
+    if (state.peer_proposed) {
+        state.status = "matched";
+    }
+    await saveThread(state);
+    return state;
+}
+// Decline a match or end the negotiation
+export async function declineMatch(nsec, thread_id, relays) {
+    const state = await loadThread(thread_id);
+    if (!state)
+        throw new Error(`Thread ${thread_id} not found`);
+    await sendEnd(nsec, state.peer_pubkey, thread_id, relays);
+    state.status = "declined";
+    state.last_activity = new Date().toISOString();
+    await saveThread(state);
+}
+// ── Private helpers ───────────────────────────────────────────────────────────
+async function sendEnd(nsec, peerNpub, thread_id, relays) {
+    await publishMessage(nsec, peerNpub, {
+        truematch: "2.0",
+        thread_id,
+        type: "end",
+        timestamp: new Date().toISOString(),
+        content: "",
+    }, relays);
+}

package/dist/nostr.d.ts

@@ -0,0 +1,5 @@
+import type { TrueMatchMessage } from "./types.js";
+export declare const DEFAULT_RELAYS: string[];
+export declare function publishMessage(senderNsec: string, recipientNpub: string, message: TrueMatchMessage, relays?: string[]): Promise<void>;
+export declare function subscribeToMessages(recipientNsec: string, recipientNpub: string, onMessage: (from: string, message: TrueMatchMessage) => Promise<void>, relays?: string[], since?: number, onEose?: () => void): Promise<() => void>;
+export declare function checkRelayConnectivity(relays?: string[]): Promise<Record<string, boolean>>;

package/dist/nostr.js

@@ -0,0 +1,117 @@
+import { SimplePool, finalizeEvent, verifyEvent, } from "nostr-tools";
+import { nip04 } from "nostr-tools";
+import { hexToBytes } from "nostr-tools/utils";
+// Public Nostr relays — agents must publish to ≥ 2 relays per spec
+export const DEFAULT_RELAYS = [
+    "wss://relay.damus.io",
+    "wss://nos.lol",
+    "wss://relay.nostr.band",
+    "wss://nostr.mom",
+];
+// NIP-04 kind for encrypted DMs.
+// NOTE: NIP-04 is deprecated by the Nostr protocol in favour of NIP-17 (gift-wrapped DMs).
+// NIP-17 hides sender, recipient, and timestamp from relay operators. A future version of
+// TrueMatch should migrate to NIP-17 / NIP-59 for stronger metadata privacy.
+const KIND_ENCRYPTED_DM = 4;
+function encryptMessage(senderNsec, recipientNpub, message) {
+    const plaintext = JSON.stringify(message);
+    return nip04.encrypt(senderNsec, recipientNpub, plaintext);
+}
+function decryptMessage(recipientNsec, senderNpub, ciphertext) {
+    const plaintext = nip04.decrypt(recipientNsec, senderNpub, ciphertext);
+    return JSON.parse(plaintext);
+}
+export async function publishMessage(senderNsec, recipientNpub, message, relays = DEFAULT_RELAYS) {
+    const ciphertext = encryptMessage(senderNsec, recipientNpub, message);
+    const eventTemplate = {
+        kind: KIND_ENCRYPTED_DM,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [["p", recipientNpub]],
+        content: ciphertext,
+    };
+    const secretKeyBytes = hexToBytes(senderNsec);
+    const signedEvent = finalizeEvent(eventTemplate, secretKeyBytes);
+    const pool = new SimplePool();
+    try {
+        const results = await Promise.allSettled(pool.publish(relays, signedEvent));
+        const succeeded = results.filter((r) => r.status === "fulfilled").length;
+        if (succeeded === 0) {
+            throw new Error("Failed to publish to any relay");
+        }
+    }
+    finally {
+        pool.close(relays);
+    }
+}
+// Maximum number of event IDs to keep in the deduplication set for long-running subscriptions.
+// When exceeded, the set is cleared (a handful of relayed duplicates may slip through briefly).
+const MAX_SEEN_IDS = 1000;
+export async function subscribeToMessages(recipientNsec, recipientNpub, onMessage, relays = DEFAULT_RELAYS, since, onEose) {
+    const pool = new SimplePool();
+    // Deduplicate events delivered by multiple relays (bounded to prevent unbounded growth)
+    const seenEventIds = new Set();
+    const sub = pool.subscribeMany(relays, {
+        kinds: [KIND_ENCRYPTED_DM],
+        "#p": [recipientNpub],
+        since: since ?? Math.floor(Date.now() / 1000) - 60 * 60, // last hour
+    }, {
+        onevent: async (event) => {
+            // NIP-01: verify event signature before processing
+            if (!verifyEvent(event))
+                return;
+            // Skip duplicates (same event from multiple relays)
+            if (seenEventIds.has(event.id))
+                return;
+            // Bound the deduplication set to prevent unbounded memory growth
+            if (seenEventIds.size >= MAX_SEEN_IDS)
+                seenEventIds.clear();
+            seenEventIds.add(event.id);
+            const senderNpub = event.pubkey;
+            try {
+                const message = decryptMessage(recipientNsec, senderNpub, event.content);
+                // Only process TrueMatch protocol messages
+                if (typeof message === "object" &&
+                    message !== null &&
+                    "truematch" in message &&
+                    message.truematch === "2.0") {
+                    await onMessage(senderNpub, message);
+                }
+            }
+            catch {
+                // Ignore messages that fail to decrypt or parse
+            }
+        },
+        oneose: () => {
+            // Historical replay complete — live events follow from here
+            onEose?.();
+        },
+    });
+    return () => {
+        sub.close();
+        pool.close(relays);
+    };
+}
+export async function checkRelayConnectivity(relays = DEFAULT_RELAYS) {
+    const results = {};
+    await Promise.all(relays.map(async (relay) => {
+        try {
+            const ws = new WebSocket(relay);
+            await new Promise((resolve, reject) => {
+                ws.onopen = () => {
+                    ws.close();
+                    resolve();
+                };
+                ws.onerror = () => reject(new Error("connection failed"));
+                setTimeout(() => {
+                    ws.close();
+                    reject(new Error("timeout"));
+                }, 5000);
+            });
+            results[relay] = true;
+        }
+        catch {
+            results[relay] = false;
+        }
+    }));
+    return results;
+}

package/dist/observation.d.ts

@@ -0,0 +1,19 @@
+import type { ObservationSummary } from "./types.js";
+export declare const DIMENSION_FLOORS: {
+    readonly attachment: 0.55;
+    readonly core_values: 0.55;
+    readonly communication: 0.55;
+    readonly emotional_regulation: 0.6;
+    readonly humor: 0.5;
+    readonly life_velocity: 0.5;
+    readonly dealbreakers: 0.6;
+    readonly conflict_resolution: 0.55;
+    readonly interdependence_model: 0.5;
+};
+export declare const ELIGIBILITY_FRESHNESS_HOURS = 72;
+export declare function loadObservation(): Promise<ObservationSummary | null>;
+export declare function saveObservation(obs: ObservationSummary): Promise<void>;
+export declare function isEligible(obs: ObservationSummary): boolean;
+export declare function isStale(obs: ObservationSummary): boolean;
+export declare function emptyObservation(): ObservationSummary;
+export declare function eligibilityReport(obs: ObservationSummary): string;

package/dist/observation.js

@@ -0,0 +1,136 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { TRUEMATCH_DIR } from "./identity.js";
+const OBSERVATION_FILE = join(TRUEMATCH_DIR, "observation.json");
+// Global minimums — cross-session sanity check
+const GLOBAL_MIN_CONVERSATIONS = 2;
+const GLOBAL_MIN_DAYS = 2;
+// Per-dimension confidence floors (psychologist-derived)
+// attachment/emotional_regulation: high contextual sensitivity → higher floor
+// dealbreakers: can surface in a single conversation → higher floor, no day req
+// communication: 0.55 (Knapp et al. — equal predictive weight to attachment)
+// conflict_resolution: 0.55 (Gottman Four Horsemen — distinct from emotional_regulation)
+// interdependence_model: 0.50 (Baxter & Montgomery — connection-autonomy dialectic)
+export const DIMENSION_FLOORS = {
+    attachment: 0.55,
+    core_values: 0.55,
+    communication: 0.55,
+    emotional_regulation: 0.6,
+    humor: 0.5,
+    life_velocity: 0.5,
+    dealbreakers: 0.6,
+    conflict_resolution: 0.55,
+    interdependence_model: 0.5,
+};
+// Manifest is stale if eligibility was last computed more than this many hours ago.
+// Bridge should trigger re-synthesis if stale.
+export const ELIGIBILITY_FRESHNESS_HOURS = 72;
+export async function loadObservation() {
+    if (!existsSync(OBSERVATION_FILE))
+        return null;
+    const raw = await readFile(OBSERVATION_FILE, "utf8");
+    return JSON.parse(raw);
+}
+export async function saveObservation(obs) {
+    const now = new Date().toISOString();
+    const updated = {
+        ...obs,
+        updated_at: now,
+        eligibility_computed_at: now,
+        matching_eligible: isEligible(obs),
+    };
+    await writeFile(OBSERVATION_FILE, JSON.stringify(updated, null, 2), "utf8");
+}
+export function isEligible(obs) {
+    if (obs.conversation_count < GLOBAL_MIN_CONVERSATIONS)
+        return false;
+    if (obs.observation_span_days < GLOBAL_MIN_DAYS)
+        return false;
+    if (obs.dealbreaker_gate_state === "below_floor")
+        return false;
+    if (obs.dealbreaker_gate_state === "none_observed")
+        return false;
+    return (obs.attachment.confidence >= DIMENSION_FLOORS.attachment &&
+        obs.core_values.confidence >= DIMENSION_FLOORS.core_values &&
+        obs.communication.confidence >= DIMENSION_FLOORS.communication &&
+        obs.emotional_regulation.confidence >=
+            DIMENSION_FLOORS.emotional_regulation &&
+        obs.humor.confidence >= DIMENSION_FLOORS.humor &&
+        obs.life_velocity.confidence >= DIMENSION_FLOORS.life_velocity &&
+        obs.dealbreakers.confidence >= DIMENSION_FLOORS.dealbreakers &&
+        obs.conflict_resolution.confidence >=
+            DIMENSION_FLOORS.conflict_resolution &&
+        obs.interdependence_model.confidence >=
+            DIMENSION_FLOORS.interdependence_model);
+}
+export function isStale(obs) {
+    const computedAt = new Date(obs.eligibility_computed_at).getTime();
+    return Date.now() - computedAt > ELIGIBILITY_FRESHNESS_HOURS * 60 * 60 * 1000;
+}
+export function emptyObservation() {
+    const now = new Date().toISOString();
+    const emptyDim = {
+        confidence: 0,
+        observation_count: 0,
+        behavioral_context_diversity: "low",
+    };
+    return {
+        updated_at: now,
+        eligibility_computed_at: now,
+        matching_eligible: false,
+        conversation_count: 0,
+        observation_span_days: 0,
+        attachment: { ...emptyDim },
+        core_values: { ...emptyDim },
+        communication: { ...emptyDim },
+        emotional_regulation: { ...emptyDim },
+        humor: { ...emptyDim },
+        life_velocity: { ...emptyDim },
+        dealbreakers: { ...emptyDim },
+        conflict_resolution: { ...emptyDim },
+        interdependence_model: { ...emptyDim },
+        dealbreaker_gate_state: "none_observed",
+        inferred_intent_category: "unclear",
+    };
+}
+export function eligibilityReport(obs) {
+    const lines = [];
+    const pass = (label, ok, detail) => lines.push(`${ok ? "✓" : "✗"} ${label}: ${detail}`);
+    pass("Conversations", obs.conversation_count >= GLOBAL_MIN_CONVERSATIONS, `${obs.conversation_count} / ${GLOBAL_MIN_CONVERSATIONS} required`);
+    pass("Observation span", obs.observation_span_days >= GLOBAL_MIN_DAYS, `${obs.observation_span_days} days / ${GLOBAL_MIN_DAYS} required`);
+    pass("Dealbreaker gate", obs.dealbreaker_gate_state !== "below_floor" &&
+        obs.dealbreaker_gate_state !== "none_observed", obs.dealbreaker_gate_state);
+    const dims = [
+        ["Attachment", obs.attachment, DIMENSION_FLOORS.attachment],
+        ["Core values", obs.core_values, DIMENSION_FLOORS.core_values],
+        ["Communication", obs.communication, DIMENSION_FLOORS.communication],
+        [
+            "Emotional regulation",
+            obs.emotional_regulation,
+            DIMENSION_FLOORS.emotional_regulation,
+        ],
+        ["Humor", obs.humor, DIMENSION_FLOORS.humor],
+        ["Life velocity", obs.life_velocity, DIMENSION_FLOORS.life_velocity],
+        ["Dealbreakers", obs.dealbreakers, DIMENSION_FLOORS.dealbreakers],
+        [
+            "Conflict resolution",
+            obs.conflict_resolution,
+            DIMENSION_FLOORS.conflict_resolution,
+        ],
+        [
+            "Interdependence model",
+            obs.interdependence_model,
+            DIMENSION_FLOORS.interdependence_model,
+        ],
+    ];
+    for (const [name, dim, floor] of dims) {
+        const diversity = dim.behavioral_context_diversity !== "low" ? "" : " [low diversity]";
+        pass(name, dim.confidence >= floor, `confidence ${dim.confidence.toFixed(2)} / ${floor.toFixed(2)} required (${dim.observation_count} signals)${diversity}`);
+    }
+    const stale = isStale(obs);
+    if (stale) {
+        lines.push(`⚠ Manifest stale — last computed ${obs.eligibility_computed_at}. Run: truematch observe --update`);
+    }
+    return lines.join("\n");
+}

package/dist/plugin.d.ts

@@ -0,0 +1,31 @@
+interface PluginEvent {
+    type: string;
+    action: string;
+    messages: string[];
+}
+interface PluginHookBeforePromptBuildResult {
+    prependContext?: string;
+    systemPrompt?: string;
+}
+interface PluginAPI {
+    on(event: "before_prompt_build", handler: (event: PluginEvent) => PluginHookBeforePromptBuildResult | void | Promise<PluginHookBeforePromptBuildResult | void>): void;
+    on(event: "session_start" | "session_end", handler: (event: PluginEvent) => void | Promise<void>): void;
+    registerHook(event: string, handler: (event: PluginEvent) => void, meta?: {
+        name?: string;
+        description?: string;
+    }): void;
+    registerTool(tool: {
+        name: string;
+        description: string;
+        handler: (rawArgs: string) => string;
+    }): void;
+}
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    kind: string;
+    register(api: PluginAPI): void;
+};
+export default _default;