talking-stick 0.1.3 → 0.2.0

package/dist/service.js

@@ -7,6 +7,16 @@ import { openDatabase, withImmediateTransaction } from "./db.js";
 import { ProtocolError } from "./errors.js";
 import { createSystemProcessInspector } from "./process-utils.js";
 const MAX_NOTE_BODY_BYTES = 16 * 1024;
+const MAX_MESSAGE_BODY_BYTES = 4096;
+const KNOWN_EVENT_TYPES = [
+    "claim",
+    "release",
+    "pass",
+    "takeover",
+    "close",
+    "kick",
+    "message_sent"
+];
 export class TalkingStickService {
     db;
     policy;
@@ -442,6 +452,95 @@ export class TalkingStickService {
             .all(input.room_id, afterEventSeq, limit)
             .map((row) => this.mapEvent(row));
     }
+    sendMessage(input) {
+        assertNonEmpty(input.agent_id, "agent_id");
+        assertNonEmpty(input.room_id, "room_id");
+        const body = input.body ?? "";
+        if (body.length === 0) {
+            throw new ProtocolError("invalid_body", "Message body must not be empty.");
+        }
+        const byteLength = Buffer.byteLength(body, "utf8");
+        if (byteLength > MAX_MESSAGE_BODY_BYTES) {
+            throw new ProtocolError("message_too_large", `Message body exceeds ${MAX_MESSAGE_BODY_BYTES} bytes.`, { supplied: byteLength });
+        }
+        const deliveryHint = input.delivery_hint ?? "normal";
+        if (deliveryHint !== "normal" && deliveryHint !== "interrupt") {
+            throw new ProtocolError("invalid_delivery_hint", "delivery_hint must be 'normal' or 'interrupt'.");
+        }
+        const now = this.now();
+        const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
+        return withImmediateTransaction(this.db, () => {
+            const room = this.requireRoom(input.room_id);
+            if (room.state === "closed") {
+                throw new ProtocolError("room_closed", "Messages cannot be sent to a closed room.", { room_id: input.room_id });
+            }
+            this.touchMember(input.room_id, input.agent_id, timestamp);
+            if (input.to_agent_id) {
+                const target = this.getMember(input.room_id, input.to_agent_id);
+                if (!target) {
+                    throw new ProtocolError("unknown_recipient", "to_agent_id is not a member of this room.", { to_agent_id: input.to_agent_id });
+                }
+            }
+            const eventSeq = this.appendEvent({
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                event_type: "message_sent",
+                from_agent_id: input.agent_id,
+                to_agent_id: input.to_agent_id ?? null,
+                handoff: null,
+                reason: null,
+                created_at: timestamp,
+                payload: { body, delivery_hint: deliveryHint }
+            });
+            const row = this.db
+                .prepare("SELECT event_id FROM room_events WHERE event_seq = ?")
+                .get(eventSeq);
+            return {
+                event_seq: eventSeq,
+                event_id: row?.event_id ?? "",
+                created_at: timestamp
+            };
+        });
+    }
+    async waitForEvents(input) {
+        assertNonEmpty(input.room_id, "room_id");
+        this.requireRoom(input.room_id);
+        const targetFilter = input.target_agent_id ?? "self";
+        if (targetFilter === "self" && !input.agent_id) {
+            throw new ProtocolError("agent_id_required", "agent_id is required when target_agent_id is 'self'.");
+        }
+        const eventTypes = normalizeEventTypeFilter(input.event_type);
+        const afterEventSeq = input.after_event_seq ?? 0;
+        const maxWaitMs = Math.min(Math.max(input.max_wait_ms ?? this.policy.waitForEventsMaxWaitMs, 0), this.policy.waitForEventsMaxWaitMs);
+        const deadline = Date.now() + maxWaitMs;
+        while (true) {
+            const events = this.queryEvents({
+                room_id: input.room_id,
+                after_event_seq: afterEventSeq,
+                event_types: eventTypes,
+                target: targetFilter,
+                caller_agent_id: input.agent_id ?? null,
+                from_agent_id: input.from_agent_id ?? null,
+                limit: this.policy.waitForEventsBatchLimit
+            });
+            if (events.length > 0 || Date.now() >= deadline) {
+                const lastSeq = events.length > 0
+                    ? events[events.length - 1].event_seq
+                    : afterEventSeq;
+                return { events, cursor_event_seq: lastSeq };
+            }
+            const remainingMs = deadline - Date.now();
+            await sleep(Math.min(this.policy.waitForEventsPollMs, remainingMs));
+        }
+    }
+    getLatestEventSeq(input) {
+        assertNonEmpty(input.room_id, "room_id");
+        this.requireRoom(input.room_id);
+        return (this.db
+            .prepare("SELECT MAX(event_seq) AS event_seq FROM room_events WHERE room_id = ?")
+            .get(input.room_id)?.event_seq ?? 0);
+    }
     addNote(input) {
         assertNonEmpty(input.agent_id, "agent_id");
         assertNonEmpty(input.room_id, "room_id");
@@ -682,7 +781,11 @@ export class TalkingStickService {
         if (forceNew) {
             const exactRoom = this.findRoomByCanonicalPath(resolved.canonical_context_path);
             if (exactRoom) {
-                return { room: exactRoom, joinedExistingRoom: true };
+                return {
+                    room: exactRoom,
+                    joinedExistingRoom: true,
+                    warning: `force_new had no effect: a room already exists at ${exactRoom.canonical_path}. force_new only creates a nested room when an ancestor room exists; same-path duplicates are not supported. To get a fresh room for a separate topic, join a distinct subpath.`
+                };
             }
             return {
                 room: this.createRoom(resolved.canonical_context_path, timestamp),
@@ -979,13 +1082,52 @@ export class TalkingStickService {
           to_agent_id,
           handoff_json,
           reason,
-          created_at
+          created_at,
+          payload_json
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `)
-            .run(randomUUID(), input.room_id, input.turn_id, input.event_type, input.from_agent_id, input.to_agent_id, input.handoff ? JSON.stringify(input.handoff) : null, input.reason, input.created_at);
+            .run(randomUUID(), input.room_id, input.turn_id, input.event_type, input.from_agent_id, input.to_agent_id, input.handoff ? JSON.stringify(input.handoff) : null, input.reason, input.created_at, input.payload ? JSON.stringify(input.payload) : null);
         return Number(result.lastInsertRowid);
     }
+    queryEvents(input) {
+        const clauses = ["room_id = ?", "event_seq > ?"];
+        const params = [input.room_id, input.after_event_seq];
+        if (input.event_types) {
+            clauses.push(`event_type IN (${input.event_types.map(() => "?").join(", ")})`);
+            params.push(...input.event_types);
+        }
+        if (input.target === "self") {
+            if (!input.caller_agent_id) {
+                throw new ProtocolError("agent_id_required", "agent_id is required when target_agent_id is 'self'.");
+            }
+            clauses.push(`(
+          (event_type = 'message_sent' AND (to_agent_id = ? OR (to_agent_id IS NULL AND from_agent_id != ?)))
+          OR
+          (event_type != 'message_sent' AND (to_agent_id = ? OR from_agent_id = ?))
+        )`);
+            params.push(input.caller_agent_id, input.caller_agent_id, input.caller_agent_id, input.caller_agent_id);
+        }
+        else if (input.target !== "any") {
+            clauses.push("to_agent_id = ?");
+            params.push(input.target);
+        }
+        if (input.from_agent_id) {
+            clauses.push("from_agent_id = ?");
+            params.push(input.from_agent_id);
+        }
+        params.push(Math.min(Math.max(input.limit, 1), 500));
+        return this.db
+            .prepare(`
+        SELECT *
+        FROM room_events
+        WHERE ${clauses.join(" AND ")}
+        ORDER BY event_seq
+        LIMIT ?
+      `)
+            .all(...params)
+            .map((row) => this.mapEvent(row));
+    }
     getRoomRow(roomId) {
         return this.db
             .prepare("SELECT * FROM path_rooms WHERE room_id = ?")
@@ -1302,6 +1444,9 @@ export class TalkingStickService {
         };
     }
     mapEvent(row) {
+        const payload = row.event_type === "message_sent" && row.payload_json
+            ? JSON.parse(row.payload_json)
+            : null;
         return {
             event_seq: row.event_seq,
             event_id: row.event_id,
@@ -1314,7 +1459,8 @@ export class TalkingStickService {
                 ? JSON.parse(row.handoff_json)
                 : null,
             reason: row.reason,
-            created_at: row.created_at
+            created_at: row.created_at,
+            payload
         };
     }
 }
@@ -1445,6 +1591,21 @@ function validateHandoff(handoff) {
         throw new ProtocolError("invalid_handoff", "handoff.artifacts must be an array when provided.", { field: "artifacts" });
     }
 }
+function normalizeEventTypeFilter(filter) {
+    if (filter === undefined) {
+        return null;
+    }
+    const values = Array.isArray(filter) ? filter : [filter];
+    if (values.length === 0) {
+        throw new ProtocolError("invalid_event_type_filter", "event_type filter must not be empty.");
+    }
+    for (const value of values) {
+        if (!KNOWN_EVENT_TYPES.includes(value)) {
+            throw new ProtocolError("invalid_event_type_filter", `Unsupported event_type: ${value}.`);
+        }
+    }
+    return values;
+}
 function assertNonEmpty(value, field) {
     if (!value || !value.trim()) {
         throw new ProtocolError("invalid_input", `${field} must be non-empty.`, {