From 15768a50a66842a50b1f3c5c71f7695bffcd20b5 Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Mon, 9 Nov 2026 17:41:17 +0530 Subject: [PATCH 1/4] fix(kin): owner chat messages wake the lead Nothing in the server turned chat posts into KinEvents, so a human message in the lead's direct chat landed in kin_messages and never reached kin_events or kin_wakeups. ChatWake subscribes to every organization on KinChatHub and enqueues chat.message and widget.action events for the lead the floor manager would pick. Event ids derive from the message, so replays collapse, and on startup it catches up on unanswered human posts from the last 24 hours. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/chat/KinChatHub.ts | 13 +- apps/server/src/kin/lead/ChatWake.test.ts | 218 ++++++++++++++++++++++ apps/server/src/kin/lead/ChatWake.ts | 139 ++++++++++++++ apps/server/src/kin/lead/layer.test.ts | 3 +- apps/server/src/kin/lead/layer.ts | 5 +- apps/server/src/kin/mcp/layer.test.ts | 4 +- docs/kin/specs/lead.md | 24 +-- 7 files changed, 389 insertions(+), 17 deletions(-) create mode 100644 apps/server/src/kin/lead/ChatWake.test.ts create mode 100644 apps/server/src/kin/lead/ChatWake.ts diff --git a/apps/server/src/kin/chat/KinChatHub.ts b/apps/server/src/kin/chat/KinChatHub.ts index ec5d5cce89105..af75435a4f85d 100644 --- a/apps/server/src/kin/chat/KinChatHub.ts +++ b/apps/server/src/kin/chat/KinChatHub.ts @@ -45,6 +45,8 @@ export class KinChatHub extends Context.Service< never, Scope.Scope >; + /** Every organization's committed events, unfiltered. Server consumers only, never a client. */ + readonly subscribeAll: Effect.Effect, never, Scope.Scope>; } >()("t3/kin/chat/KinChatHub") {} @@ -52,8 +54,11 @@ const make = Effect.gen(function* () { const sql = yield* SqlClient.SqlClient; const repo = yield* Repository.KinChatRepository; const hubs = new Map>(); + let all: PubSub.PubSub | undefined; yield* Effect.addFinalizer(() => - Effect.forEach(hubs.values(), PubSub.shutdown, { discard: true }), + Effect.forEach([...hubs.values(), ...(all === undefined ? [] : [all])], PubSub.shutdown, { + discard: true, + }), ); const subscribe = Effect.fn("KinChatHub.subscribe")(function* (orgId: KinOrgId) { let hub = hubs.get(orgId); @@ -70,9 +75,15 @@ const make = Effect.gen(function* () { Effect.gen(function* () { const hub = hubs.get(event.orgId); if (hub !== undefined) yield* PubSub.publish(hub, event); + if (all !== undefined) yield* PubSub.publish(all, event); }), ); }), + subscribeAll: Effect.gen(function* () { + const created = yield* PubSub.unbounded(); + all ??= created; + return Stream.fromEffectRepeat(PubSub.take(yield* PubSub.subscribe(all))); + }).pipe(Effect.withSpan("KinChatHub.subscribeAll")), subscribeForViewer: Effect.fn("KinChatHub.subscribeForViewer")(function* (identity) { const subscription = yield* subscribe(identity.orgId); return Stream.fromEffectRepeat(PubSub.take(subscription)).pipe( diff --git a/apps/server/src/kin/lead/ChatWake.test.ts b/apps/server/src/kin/lead/ChatWake.test.ts new file mode 100644 index 0000000000000..515dadc56ad3d --- /dev/null +++ b/apps/server/src/kin/lead/ChatWake.test.ts @@ -0,0 +1,218 @@ +import { assert, describe, it } from "@effect/vitest"; +import { KinEvent, KinMessage, KinOrgId } from "@t3tools/contracts"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Queue from "effect/Queue"; +import * as Schema from "effect/Schema"; +import * as SqlClient from "effect/sql/SqlClient"; + +import * as Sqlite from "../../persistence/Sqlite.ts"; +import * as Hub from "../chat/KinChatHub.ts"; +import * as Repository from "../chat/KinChatRepository.ts"; +import * as KinPersistence from "../persistence/KinPersistence.ts"; +import * as ChatWake from "./ChatWake.ts"; +import * as KinEventQueue from "./KinEventQueue.ts"; + +const decodeMessage = Schema.decodeUnknownSync(KinMessage); +const decodeEventJson = Schema.decodeEffect(Schema.fromJsonString(KinEvent)); +const createdAt = "1970-01-01T00:00:00.000Z"; + +const database = Layer.provideMerge(KinPersistence.layer, Sqlite.layerMemory); +const services = Layer.mergeAll(KinEventQueue.layer, Hub.layer).pipe( + Layer.provideMerge(Repository.layer), + Layer.provideMerge(database), +); + +const seed = Effect.fn("test.seed")(function* (org: string) { + const sql = yield* SqlClient.SqlClient; + const lead = `lead-${org}`; + yield* sql`INSERT INTO kin_orgs VALUES (${org}, 'Kin', ${createdAt})`; + yield* sql`INSERT INTO kin_people (person_id, org_id, handle, display_name, created_at) + VALUES (${`owner-${org}`}, ${org}, ${`owner-${org}`}, 'Owner', ${createdAt})`; + yield* sql`INSERT INTO kin_agents (agent_id, org_id, display_name, role, owner_person_id, created_at) + VALUES (${lead}, ${org}, 'Lead', 'lead', ${`owner-${org}`}, ${createdAt})`; + yield* sql`INSERT INTO kin_chats (chat_id, org_id, kind, direct_key, last_seq, created_at) + VALUES (${`chat-${org}`}, ${org}, 'direct', ${`direct-${org}`}, 0, ${createdAt})`; + yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, person_id, role, joined_at) + VALUES (${`owner-member-${org}`}, ${org}, ${`chat-${org}`}, 'person', ${`owner-${org}`}, 'owner', ${createdAt})`; + yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, agent_id, role, joined_at) + VALUES (${`lead-member-${org}`}, ${org}, ${`chat-${org}`}, 'agent', ${lead}, 'member', ${createdAt})`; + yield* sql`INSERT INTO kin_leads (agent_id, org_id, name, level_since, models_json, worker_projects_json, owner_chat_id) + VALUES (${lead}, ${org}, 'Lead', 0, '{}', '[]', ${`chat-${org}`})`; +}); + +const message = ( + org: string, + messageId: string, + options: { readonly seq?: number; readonly agent?: boolean; readonly tap?: string } = {}, +) => + decodeMessage({ + orgId: org, + chatId: `chat-${org}`, + messageId, + seq: options.seq ?? 1, + author: + options.agent === true + ? { + _tag: "agent", + agentId: `lead-${org}`, + memberId: `lead-member-${org}`, + ownerPersonId: `owner-${org}`, + threadId: `thread-${org}`, + } + : { _tag: "human", personId: `owner-${org}`, memberId: `owner-member-${org}` }, + authorRole: options.agent === true ? "member" : "owner", + kind: options.tap === undefined ? "text" : "widget_action", + body: + options.tap === undefined + ? "Can you check the release?" + : JSON.stringify({ widgetId: "widget", revision: 1, actionId: options.tap }), + intent: options.agent === true ? "answer" : null, + mentions: [], + replyTo: null, + widgetId: null, + floorRunId: null, + status: "posted", + sentBy: null, + createdAt, + editedAt: null, + }); + +const storeMessage = Effect.fn("test.storeMessage")(function* (row: KinMessage) { + const sql = yield* SqlClient.SqlClient; + const agent = row.author._tag === "agent" ? row.author : undefined; + const human = row.author._tag === "human" ? row.author : undefined; + yield* sql`INSERT INTO kin_messages (message_id, org_id, chat_id, seq, author_kind, author_person_id, + author_agent_id, author_owner_person_id, author_thread_id, author_member_id, author_role, kind, body, + intent, mentions_json, status, created_at) + VALUES (${row.messageId}, ${row.orgId}, ${row.chatId}, ${row.seq}, ${row.author._tag}, + ${human?.personId ?? null}, ${agent?.agentId ?? null}, ${agent?.ownerPersonId ?? null}, + ${agent?.threadId ?? null}, ${agent?.memberId ?? human?.memberId ?? null}, ${row.authorRole}, + ${row.kind}, ${row.body}, ${row.intent}, '[]', ${row.status}, ${row.createdAt})`; +}); + +// Records every enqueue result, so tests await the bridge's work instead of sleeping. +const start = Effect.fn("test.start")(function* () { + const results = yield* Queue.unbounded<{ + readonly event: KinEvent; + readonly duplicate: boolean; + }>(); + const queue = yield* KinEventQueue.KinEventQueue; + yield* Layer.build( + ChatWake.layer.pipe( + Layer.provide( + Layer.succeed(KinEventQueue.KinEventQueue, { + ...queue, + enqueue: (event) => + queue.enqueue(event).pipe(Effect.tap((result) => Queue.offer(results, result))), + }), + ), + ), + ); + return results; +}); + +const storedEvents = Effect.fn("test.storedEvents")(function* () { + const sql = yield* SqlClient.SqlClient; + const rows = yield* sql<{ json: string; priority: string }>` + SELECT json, priority FROM kin_events ORDER BY event_id`; + return yield* Effect.forEach(rows, (row) => + decodeEventJson(row.json).pipe(Effect.map((event) => ({ event, priority: row.priority }))), + ); +}); + +describe("ChatWake", () => { + it.effect("wakes the lead once for each owner message and widget tap in its chat", () => + Effect.gen(function* () { + yield* seed("a"); + const hub = yield* Hub.KinChatHub; + const results = yield* start(); + const orgId = KinOrgId.make("a"); + yield* hub.publish({ type: "message.posted", orgId, message: message("a", "m1") }); + yield* hub.publish({ type: "message.posted", orgId, message: message("a", "m1") }); + yield* hub.publish({ + type: "message.posted", + orgId, + message: message("a", "tap", { seq: 2, tap: "approve" }), + }); + const [first, replay, tap] = yield* Queue.takeN(results, 3); + assert.strictEqual(first?.duplicate, false); + assert.strictEqual(replay?.duplicate, true); + assert.strictEqual(tap?.duplicate, false); + const stored = yield* storedEvents(); + assert.deepStrictEqual( + stored.map(({ event, priority }) => [event._tag, event.eventId, priority]), + [ + ["chat.message", "chat-message:m1:lead-a", "P0"], + ["widget.action", "widget-action:tap:lead-a", "P0"], + ], + ); + const event = stored[0]!.event; + assert.strictEqual(event.agentId, "lead-a"); + assert.strictEqual(event.dedupeKey, event.eventId); + assert.deepStrictEqual(event.provenance, message("a", "m1").author); + assert.strictEqual( + stored[1]!.event._tag === "widget.action" && stored[1]!.event.actionId, + "approve", + ); + }).pipe(Effect.provide(services)), + ); + + it.effect("never wakes a lead for its own posts or after retirement", () => + Effect.gen(function* () { + yield* seed("a"); + yield* seed("b"); + const sql = yield* SqlClient.SqlClient; + yield* sql`UPDATE kin_agents SET retired_at = ${createdAt} WHERE agent_id = 'lead-b'`; + const hub = yield* Hub.KinChatHub; + const results = yield* start(); + yield* hub.publish({ + type: "message.posted", + orgId: KinOrgId.make("a"), + message: message("a", "reply", { agent: true }), + }); + yield* hub.publish({ + type: "message.posted", + orgId: KinOrgId.make("b"), + message: message("b", "to-retired"), + }); + yield* hub.publish({ + type: "message.posted", + orgId: KinOrgId.make("a"), + message: message("a", "sentinel", { seq: 2 }), + }); + // The stream is ordered, so the sentinel's result means the earlier posts were handled. + const result = yield* Queue.take(results); + assert.strictEqual(result.event.eventId, "chat-message:sentinel:lead-a"); + assert.deepStrictEqual( + (yield* storedEvents()).map(({ event }) => event.eventId), + ["chat-message:sentinel:lead-a"], + ); + }).pipe(Effect.provide(services)), + ); + + it.effect("catches up on owner messages the lead has not answered since its last post", () => + Effect.gen(function* () { + yield* seed("a"); + yield* storeMessage(message("a", "answered", { seq: 1 })); + yield* storeMessage(message("a", "lead-reply", { seq: 2, agent: true })); + yield* storeMessage(message("a", "unanswered", { seq: 3 })); + const hub = yield* Hub.KinChatHub; + const results = yield* start(); + assert.strictEqual( + (yield* Queue.take(results)).event.eventId, + "chat-message:unanswered:lead-a", + ); + yield* hub.publish({ + type: "message.posted", + orgId: KinOrgId.make("a"), + message: message("a", "live", { seq: 4 }), + }); + assert.strictEqual((yield* Queue.take(results)).event.eventId, "chat-message:live:lead-a"); + assert.deepStrictEqual( + (yield* storedEvents()).map(({ event }) => event.eventId), + ["chat-message:live:lead-a", "chat-message:unanswered:lead-a"], + ); + }).pipe(Effect.provide(services)), + ); +}); diff --git a/apps/server/src/kin/lead/ChatWake.ts b/apps/server/src/kin/lead/ChatWake.ts new file mode 100644 index 0000000000000..e1e9edd234fe3 --- /dev/null +++ b/apps/server/src/kin/lead/ChatWake.ts @@ -0,0 +1,139 @@ +import { + KinAgentId, + KinEventId, + KinMessageId, + KinOrgId, + TrimmedNonEmptyString, + type KinEvent, + type KinMessage, +} from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; +import * as Schema from "effect/Schema"; +import * as Stream from "effect/Stream"; +import * as SqlClient from "effect/sql/SqlClient"; + +import { forkParked } from "../../serverActivation.ts"; +import { KinChatHub } from "../chat/KinChatHub.ts"; +import { KinChatRepository } from "../chat/KinChatRepository.ts"; +import { KinEventQueue } from "./KinEventQueue.ts"; + +const decodeTap = Schema.decodeUnknownEffect( + Schema.fromJsonString(Schema.Struct({ actionId: TrimmedNonEmptyString })), +); +// Matches the resume expiry: older unanswered messages are not worth a wake-up after downtime. +const CATCH_UP_WINDOW = { hours: 24 } as const; +const CATCH_UP_LIMIT = 200; + +/** + * Turns committed human chat posts and widget taps into `chat.message` and `widget.action` + * events for the lead the floor manager would wake: mentioned leads, else the chat's lead. + */ +const make = Effect.gen(function* () { + const sql = yield* SqlClient.SqlClient; + const hub = yield* KinChatHub; + const repo = yield* KinChatRepository; + const queue = yield* KinEventQueue; + + const wake = Effect.fn("KinChatWake.wake")( + function* (message: KinMessage) { + if (message.author._tag !== "human" || message.status !== "posted") return; + if (message.kind !== "text" && message.kind !== "widget_action") return; + const leads = yield* sql<{ agentId: string; memberId: string }>` + SELECT l.agent_id AS "agentId", m.member_id AS "memberId" FROM kin_leads l + JOIN kin_agents a ON a.org_id = l.org_id AND a.agent_id = l.agent_id AND a.retired_at IS NULL + JOIN kin_chat_members m ON m.org_id = l.org_id AND m.chat_id = ${message.chatId} + AND m.principal_kind = 'agent' AND m.agent_id = l.agent_id AND m.left_at IS NULL + WHERE l.org_id = ${message.orgId} + ORDER BY CASE a.role WHEN 'lead' THEN 0 ELSE 1 END, m.joined_at, l.agent_id`; + const mentioned = leads.filter((lead) => + message.mentions.some((memberId) => memberId === lead.memberId), + ); + const targets = mentioned.length > 0 ? mentioned : leads.slice(0, 1); + if (targets.length === 0) return; + const actionId = + message.kind === "widget_action" + ? (yield* decodeTap(message.body).pipe(Effect.option)).pipe( + Option.map((tap) => tap.actionId), + ) + : Option.none(); + if (message.kind === "widget_action" && Option.isNone(actionId)) + return yield* Effect.logWarning("Kin widget action has no readable action id", { + orgId: message.orgId, + messageId: message.messageId, + }); + for (const target of targets) { + const agentId = KinAgentId.make(target.agentId); + // Every field comes from the stored message, so a replay enqueues byte-identical JSON. + const eventId = KinEventId.make( + `${message.kind === "widget_action" ? "widget-action" : "chat-message"}:${message.messageId}:${agentId}`, + ); + const base = { + orgId: message.orgId, + eventId, + agentId, + receivedAt: DateTime.makeUnsafe(message.createdAt), + dedupeKey: eventId, + provenance: message.author, + chatId: message.chatId, + messageId: message.messageId, + }; + const event: KinEvent = Option.isSome(actionId) + ? { ...base, _tag: "widget.action", actionId: actionId.value } + : { ...base, _tag: "chat.message" }; + yield* queue.enqueue(event).pipe( + Effect.catchTags({ + KinEventQueueRetiredAgent: () => Effect.void, + KinEventQueueUnknownAgent: () => Effect.void, + KinEventQueueConflict: (error) => + Effect.logWarning("Kin chat wake-up conflicts with a stored event", error), + }), + ); + } + }, + Effect.catchCause((cause) => Effect.logError("Kin chat wake-up failed", { cause })), + ); + + // Messages posted while the server was down or Kin was off never reached the hub. + const catchUp = Effect.fn("KinChatWake.catchUp")( + function* () { + const since = DateTime.formatIso(DateTime.subtract(yield* DateTime.now, CATCH_UP_WINDOW)); + const rows = yield* sql<{ orgId: string; messageId: string; createdAt: string }>` + SELECT DISTINCT m.org_id AS "orgId", m.message_id AS "messageId", m.created_at AS "createdAt" + FROM kin_leads l + JOIN kin_agents a ON a.org_id = l.org_id AND a.agent_id = l.agent_id AND a.retired_at IS NULL + JOIN kin_chat_members am ON am.org_id = l.org_id AND am.principal_kind = 'agent' + AND am.agent_id = l.agent_id AND am.left_at IS NULL + JOIN kin_messages m ON m.org_id = am.org_id AND m.chat_id = am.chat_id + WHERE m.author_kind = 'human' AND m.status = 'posted' AND m.kind IN ('text', 'widget_action') + AND m.created_at > ${since} + AND m.seq > COALESCE((SELECT MAX(x.seq) FROM kin_messages x + WHERE x.org_id = m.org_id AND x.chat_id = m.chat_id AND x.author_kind = 'agent' + AND x.author_agent_id = l.agent_id), 0) + ORDER BY m.created_at DESC, m.message_id DESC LIMIT ${CATCH_UP_LIMIT}`; + for (const row of rows) { + const message = yield* repo.getMessage({ + orgId: KinOrgId.make(row.orgId), + messageId: KinMessageId.make(row.messageId), + }); + if (Option.isSome(message)) yield* wake(message.value); + } + }, + Effect.catchCause((cause) => Effect.logError("Kin chat wake-up catch-up failed", { cause })), + ); + + // Subscribe before activation so nothing posted from here on is missed. + const events = yield* hub.subscribeAll; + yield* catchUp().pipe( + Effect.andThen( + Stream.runForEach(events, (event) => + event.type === "message.posted" ? wake(event.message) : Effect.void, + ), + ), + forkParked, + ); +}); + +export const layer = Layer.effectDiscard(make); diff --git a/apps/server/src/kin/lead/layer.test.ts b/apps/server/src/kin/lead/layer.test.ts index 8ab031f53302e..5159d52704215 100644 --- a/apps/server/src/kin/lead/layer.test.ts +++ b/apps/server/src/kin/lead/layer.test.ts @@ -7,6 +7,7 @@ import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; import * as Logger from "effect/Logger"; import * as SqlClient from "effect/sql/SqlClient"; +import * as Stream from "effect/Stream"; import * as TestClock from "effect/testing/TestClock"; import { vi } from "vite-plus/test"; import * as VcsProcess from "../../vcs/VcsProcess.ts"; @@ -22,7 +23,7 @@ import { event, harness, seed, orgId } from "./WakeupRunner.testkit.ts"; const external = Layer.mergeAll( Layer.mock(ChatService.KinChatService)({}), - Layer.mock(ChatHub.KinChatHub)({}), + Layer.mock(ChatHub.KinChatHub)({ subscribeAll: Effect.succeed(Stream.never) }), ServerConfig.layerTest(process.cwd(), { prefix: "kin-lead-layer-" }), Layer.mock(VcsProcess.VcsProcess)({}), ).pipe(Layer.provideMerge(NodeServices.layer)); diff --git a/apps/server/src/kin/lead/layer.ts b/apps/server/src/kin/lead/layer.ts index 71e79a2e67b32..07d4a7d2271cf 100644 --- a/apps/server/src/kin/lead/layer.ts +++ b/apps/server/src/kin/lead/layer.ts @@ -43,6 +43,7 @@ import * as DreamRunner from "../dreaming/DreamRunner.ts"; import * as DreamSession from "../dreaming/DreamSession.ts"; import * as Workers from "./Workers.ts"; import * as WorkerTracker from "./WorkerTracker.ts"; +import * as ChatWake from "./ChatWake.ts"; export class KinLeadStartupError extends Schema.TaggedError()( "KinLeadStartupError", @@ -196,7 +197,7 @@ const toolkit = LeadMemory.layer.pipe( ), ); -export const layer = withServices(runner); +export const layer = withServices(Layer.merge(runner, ChatWake.layer)); const tracker = Layer.effectDiscard( Effect.gen(function* () { const tracker = yield* WorkerTracker.WorkerTracker; @@ -204,7 +205,7 @@ const tracker = Layer.effectDiscard( }), ).pipe(Layer.provide(WorkerTracker.layer)); const production = withServices( - Layer.mergeAll(runner, registration, tracker).pipe( + Layer.mergeAll(runner, ChatWake.layer, registration, tracker).pipe( Layer.provideMerge(Workers.layer), Layer.provideMerge(toolkit), ), diff --git a/apps/server/src/kin/mcp/layer.test.ts b/apps/server/src/kin/mcp/layer.test.ts index 45ada9c350385..57342ec1ac444 100644 --- a/apps/server/src/kin/mcp/layer.test.ts +++ b/apps/server/src/kin/mcp/layer.test.ts @@ -186,8 +186,8 @@ it.effect.each([true, false])( ), ); const http = yield* HttpRouter.toHttpEffect(routes); - // The wake-up runner and the worker tracker. - assert.strictEqual(runnerStarts, enabled ? 2 : 0); + // The wake-up runner, the chat wake bridge and the worker tracker. + assert.strictEqual(runnerStarts, enabled ? 3 : 0); const services = yield* Deferred.await(ready); const kin = Context.get(services, Kin.KinServer); const registry = Context.get(services, McpSessions.McpSessionRegistry); diff --git a/docs/kin/specs/lead.md b/docs/kin/specs/lead.md index f0ff3f1964eb6..63aeff742a301 100644 --- a/docs/kin/specs/lead.md +++ b/docs/kin/specs/lead.md @@ -153,17 +153,19 @@ export const KinEvent = Schema.Union([ Events carry references, not bodies. The lead reads the message or payload through its tools, so the queue never holds large or secret text. `scheduledTaskId` and `webhookDeliveryId` identify the stored payload for `ScheduledTaskService.getWebhookDelivery`. `deliveryId` is GitHub’s `x-github-delivery` header; the inbox consumer uses `deliveryId` as the event’s `dedupeKey` for `github` events and `KinTriggerFired.fireId` for other kinds. The `deferral.due.subject` union directly mirrors the triggers spec’s deferral (including `phase`), reminder and followup subjects; `lateByMs` is a non-negative integer. -| Source | Event | Producer | -| ------------------------------------------------ | ----------------- | -------------------------------------------------------- | -| A person or agent posts in a chat the lead is in | `chat.message` | chat spec, after the floor manager says this lead speaks | -| A tap on a widget | `widget.action` | chat spec | -| GitHub webhook | `github` | triggers spec | -| `once` trigger on a deferral | `deferral.due` | triggers spec | -| `fixed_time` routine | `routine` | triggers spec (content below) | -| `interval` watchdog | `watchdog` | triggers spec | -| Worker run ends | `worker.report` | this spec (`WorkerTracker`) | -| Executor finishes or a grant expires | `action.resolved` | approvals spec | -| Stop switch turned off | `resume` | this spec | +| Source | Event | Producer | +| --------------------------------------- | ----------------- | --------------------------------------------------------- | +| A person posts in a chat the lead is in | `chat.message` | this spec (`ChatWake`), for the lead the floor would pick | +| A tap on a widget | `widget.action` | this spec (`ChatWake`) | +| GitHub webhook | `github` | triggers spec | +| `once` trigger on a deferral | `deferral.due` | triggers spec | +| `fixed_time` routine | `routine` | triggers spec (content below) | +| `interval` watchdog | `watchdog` | triggers spec | +| Worker run ends | `worker.report` | this spec (`WorkerTracker`) | +| Executor finishes or a grant expires | `action.resolved` | approvals spec | +| Stop switch turned off | `resume` | this spec | + +`ChatWake` subscribes to every organization on `KinChatHub` and wakes mentioned leads, else the chat's first lead, as the floor manager does. Agent and system posts never wake a lead. Event ids derive from the message and lead, so a replay collapses. Posts made while the server was down never reach the hub, so on startup it re-enqueues human posts from the last 24 hours that came after the lead's last post in that chat. All producers call one entry point: `KinEventQueue.enqueue(event)`. Nothing else may start a lead session. Scheduled tasks in particular must not launch a T3 thread with a lead prompt; the triggers spec routes their fires into `enqueue`. From 79d2fbc88dae6c6cba7694cdc5ac78b55143d0aa Mon Sep 17 00:00:00 2001 From: Surajsm60720 <1ds22is166@dsce.edu.in> Date: Mon, 9 Nov 2026 17:45:58 +0530 Subject: [PATCH 2/4] fix(kin): chat wake event ids pass the memory writer's check The memory writer refuses a wake-up whose event ids hold anything but [a-zA-Z0-9_-], so the first real wake-up from a chat message failed with "Invalid server context". Hash the readable key into the id, as the deferral and watchdog producers do, and keep the key as the dedupe key. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/lead/ChatWake.test.ts | 14 +++++++------- apps/server/src/kin/lead/ChatWake.ts | 10 ++++++++-- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/apps/server/src/kin/lead/ChatWake.test.ts b/apps/server/src/kin/lead/ChatWake.test.ts index 515dadc56ad3d..0a47b5cfe9577 100644 --- a/apps/server/src/kin/lead/ChatWake.test.ts +++ b/apps/server/src/kin/lead/ChatWake.test.ts @@ -141,7 +141,7 @@ describe("ChatWake", () => { assert.strictEqual(tap?.duplicate, false); const stored = yield* storedEvents(); assert.deepStrictEqual( - stored.map(({ event, priority }) => [event._tag, event.eventId, priority]), + stored.map(({ event, priority }) => [event._tag, event.dedupeKey, priority]), [ ["chat.message", "chat-message:m1:lead-a", "P0"], ["widget.action", "widget-action:tap:lead-a", "P0"], @@ -149,7 +149,7 @@ describe("ChatWake", () => { ); const event = stored[0]!.event; assert.strictEqual(event.agentId, "lead-a"); - assert.strictEqual(event.dedupeKey, event.eventId); + assert.match(event.eventId, /^chat-message-[a-f0-9]{32}$/); assert.deepStrictEqual(event.provenance, message("a", "m1").author); assert.strictEqual( stored[1]!.event._tag === "widget.action" && stored[1]!.event.actionId, @@ -183,9 +183,9 @@ describe("ChatWake", () => { }); // The stream is ordered, so the sentinel's result means the earlier posts were handled. const result = yield* Queue.take(results); - assert.strictEqual(result.event.eventId, "chat-message:sentinel:lead-a"); + assert.strictEqual(result.event.dedupeKey, "chat-message:sentinel:lead-a"); assert.deepStrictEqual( - (yield* storedEvents()).map(({ event }) => event.eventId), + (yield* storedEvents()).map(({ event }) => event.dedupeKey), ["chat-message:sentinel:lead-a"], ); }).pipe(Effect.provide(services)), @@ -200,7 +200,7 @@ describe("ChatWake", () => { const hub = yield* Hub.KinChatHub; const results = yield* start(); assert.strictEqual( - (yield* Queue.take(results)).event.eventId, + (yield* Queue.take(results)).event.dedupeKey, "chat-message:unanswered:lead-a", ); yield* hub.publish({ @@ -208,9 +208,9 @@ describe("ChatWake", () => { orgId: KinOrgId.make("a"), message: message("a", "live", { seq: 4 }), }); - assert.strictEqual((yield* Queue.take(results)).event.eventId, "chat-message:live:lead-a"); + assert.strictEqual((yield* Queue.take(results)).event.dedupeKey, "chat-message:live:lead-a"); assert.deepStrictEqual( - (yield* storedEvents()).map(({ event }) => event.eventId), + (yield* storedEvents()).map(({ event }) => event.dedupeKey).toSorted(), ["chat-message:live:lead-a", "chat-message:unanswered:lead-a"], ); }).pipe(Effect.provide(services)), diff --git a/apps/server/src/kin/lead/ChatWake.ts b/apps/server/src/kin/lead/ChatWake.ts index e1e9edd234fe3..3a0b15ce460f9 100644 --- a/apps/server/src/kin/lead/ChatWake.ts +++ b/apps/server/src/kin/lead/ChatWake.ts @@ -7,6 +7,9 @@ import { type KinEvent, type KinMessage, } from "@t3tools/contracts"; +// @effect-diagnostics-next-line nodeBuiltinImport:off -- a pure, synchronous id hash; Digest would add a service. +import * as NodeCrypto from "node:crypto"; + import * as DateTime from "effect/DateTime"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; @@ -67,15 +70,18 @@ const make = Effect.gen(function* () { for (const target of targets) { const agentId = KinAgentId.make(target.agentId); // Every field comes from the stored message, so a replay enqueues byte-identical JSON. + const prefix = message.kind === "widget_action" ? "widget-action" : "chat-message"; + const dedupeKey = `${prefix}:${message.messageId}:${agentId}`; + // The memory writer accepts only [a-zA-Z0-9_-] in event ids, so hash the readable key. const eventId = KinEventId.make( - `${message.kind === "widget_action" ? "widget-action" : "chat-message"}:${message.messageId}:${agentId}`, + `${prefix}-${NodeCrypto.createHash("sha256").update(dedupeKey).digest("hex").slice(0, 32)}`, ); const base = { orgId: message.orgId, eventId, agentId, receivedAt: DateTime.makeUnsafe(message.createdAt), - dedupeKey: eventId, + dedupeKey, provenance: message.author, chatId: message.chatId, messageId: message.messageId, From 9dd6a12e966377277e28d3ee0406f0ee97f1e77b Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Mon, 9 Nov 2026 19:45:07 +0530 Subject: [PATCH 3/4] fix(kin): woken leads can answer late chat posts, direct chats only A post's floor grant lapses after five minutes, so catch-up wake-ups and wake-ups held by the stop switch or budget always ended in a refused reply. The runner now re-arms the lead's unused grant on each open direct-chat run a claimed message opened, as the wake-up launches. It never issues a grant. ChatWake now wakes leads for direct chats only, catches up per organization with a per-organization limit, maps SQL errors, and a source guard keeps KinChatHub.subscribeAll out of tools and transports. The hub creates its all-org PubSub once. ChatWake tests settle on a sentinel instead of hanging. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/chat/KinChatHub.ts | 6 +- apps/server/src/kin/floor/KinFloor.ts | 30 +- apps/server/src/kin/lead/ChatWake.test.ts | 256 +++++++++++++----- apps/server/src/kin/lead/ChatWake.ts | 49 +++- apps/server/src/kin/lead/WakeupRunner.test.ts | 67 +++++ apps/server/src/kin/lead/WakeupRunner.ts | 14 +- docs/kin/specs/chat.md | 2 +- docs/kin/specs/lead.md | 4 +- 8 files changed, 343 insertions(+), 85 deletions(-) diff --git a/apps/server/src/kin/chat/KinChatHub.ts b/apps/server/src/kin/chat/KinChatHub.ts index af75435a4f85d..b02797feed9c0 100644 --- a/apps/server/src/kin/chat/KinChatHub.ts +++ b/apps/server/src/kin/chat/KinChatHub.ts @@ -80,8 +80,10 @@ const make = Effect.gen(function* () { ); }), subscribeAll: Effect.gen(function* () { - const created = yield* PubSub.unbounded(); - all ??= created; + if (all === undefined) { + const created = yield* PubSub.unbounded(); + all ??= created; + } return Stream.fromEffectRepeat(PubSub.take(yield* PubSub.subscribe(all))); }).pipe(Effect.withSpan("KinChatHub.subscribeAll")), subscribeForViewer: Effect.fn("KinChatHub.subscribeForViewer")(function* (identity) { diff --git a/apps/server/src/kin/floor/KinFloor.ts b/apps/server/src/kin/floor/KinFloor.ts index c090398cd7d5d..7a1c9da29f4cb 100644 --- a/apps/server/src/kin/floor/KinFloor.ts +++ b/apps/server/src/kin/floor/KinFloor.ts @@ -70,6 +70,15 @@ export class KinFloor extends Context.Service< message: KinMessage, chat: KinChat, ) => Effect.Effect; + /** + * Re-arms the agent's unused direct-chat grant on each open run one of `messageIds` opened, + * so a wake-up that starts after the TTL can still reply once. It never issues a grant. + */ + readonly renew: (input: { + readonly orgId: KinOrgId; + readonly agentId: KinAgentId; + readonly messageIds: ReadonlyArray; + }) => Effect.Effect; readonly authorize: ( identity: AgentIdentity, chat: KinChat, @@ -168,6 +177,25 @@ const make = Effect.gen(function* () { Effect.mapError(toPersistenceSqlError("KinFloor.open")), ); + const renew = Effect.fn("KinFloor.renew")( + function* (input: { + readonly orgId: KinOrgId; + readonly agentId: KinAgentId; + readonly messageIds: ReadonlyArray; + }) { + if (input.messageIds.length === 0) return; + const expiresAt = (yield* Clock.currentTimeMillis) + FLOOR_GRANT_TTL_MS; + // A new human message closes the run, and a reply consumes the grant, so neither re-arms. + yield* sql`UPDATE kin_floor_grants SET expires_at = MAX(expires_at, ${expiresAt}) + WHERE org_id = ${input.orgId} AND agent_id = ${input.agentId} AND consumed_at IS NULL + AND run_id IN (SELECT r.run_id FROM kin_floor_runs r + JOIN kin_chats c ON c.org_id = r.org_id AND c.chat_id = r.chat_id AND c.kind = 'direct' + WHERE r.org_id = ${input.orgId} AND r.state = 'open' + AND r.opened_by IN ${sql.in(input.messageIds)})`; + }, + Effect.mapError(toPersistenceSqlError("KinFloor.renew")), + ); + const noticeOnly = Effect.fn("KinFloor.noticeOnly")( function* (identity: AgentIdentity) { // Notice authority comes from the running wake-up's stored events, never tool input. @@ -308,6 +336,6 @@ const make = Effect.gen(function* () { }, Effect.mapError(toPersistenceSqlError("KinFloor.recordNotice")), ); - return KinFloor.of({ open, authorize, noticeOnly, admitNotice, recordNotice }); + return KinFloor.of({ open, renew, authorize, noticeOnly, admitNotice, recordNotice }); }); export const layer = Layer.effect(KinFloor, make); diff --git a/apps/server/src/kin/lead/ChatWake.test.ts b/apps/server/src/kin/lead/ChatWake.test.ts index 0a47b5cfe9577..de52d05505e95 100644 --- a/apps/server/src/kin/lead/ChatWake.test.ts +++ b/apps/server/src/kin/lead/ChatWake.test.ts @@ -1,3 +1,7 @@ +// @effect-diagnostics nodeBuiltinImport:off -- node:fs reads sources for the subscribeAll guard. +import * as NodeFS from "node:fs"; +import * as NodePath from "node:path"; + import { assert, describe, it } from "@effect/vitest"; import { KinEvent, KinMessage, KinOrgId } from "@t3tools/contracts"; import * as Effect from "effect/Effect"; @@ -5,6 +9,7 @@ import * as Layer from "effect/Layer"; import * as Queue from "effect/Queue"; import * as Schema from "effect/Schema"; import * as SqlClient from "effect/sql/SqlClient"; +import * as Stream from "effect/Stream"; import * as Sqlite from "../../persistence/Sqlite.ts"; import * as Hub from "../chat/KinChatHub.ts"; @@ -23,7 +28,10 @@ const services = Layer.mergeAll(KinEventQueue.layer, Hub.layer).pipe( Layer.provideMerge(database), ); -const seed = Effect.fn("test.seed")(function* (org: string) { +const seed = Effect.fn("test.seed")(function* ( + org: string, + kind: "direct" | "team_group" = "direct", +) { const sql = yield* SqlClient.SqlClient; const lead = `lead-${org}`; yield* sql`INSERT INTO kin_orgs VALUES (${org}, 'Kin', ${createdAt})`; @@ -32,7 +40,7 @@ const seed = Effect.fn("test.seed")(function* (org: string) { yield* sql`INSERT INTO kin_agents (agent_id, org_id, display_name, role, owner_person_id, created_at) VALUES (${lead}, ${org}, 'Lead', 'lead', ${`owner-${org}`}, ${createdAt})`; yield* sql`INSERT INTO kin_chats (chat_id, org_id, kind, direct_key, last_seq, created_at) - VALUES (${`chat-${org}`}, ${org}, 'direct', ${`direct-${org}`}, 0, ${createdAt})`; + VALUES (${`chat-${org}`}, ${org}, ${kind}, ${kind === "direct" ? `direct-${org}` : null}, 0, ${createdAt})`; yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, person_id, role, joined_at) VALUES (${`owner-member-${org}`}, ${org}, ${`chat-${org}`}, 'person', ${`owner-${org}`}, 'owner', ${createdAt})`; yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, agent_id, role, joined_at) @@ -44,11 +52,16 @@ const seed = Effect.fn("test.seed")(function* (org: string) { const message = ( org: string, messageId: string, - options: { readonly seq?: number; readonly agent?: boolean; readonly tap?: string } = {}, + options: { + readonly seq?: number; + readonly agent?: boolean; + readonly tap?: string; + readonly chat?: string; + } = {}, ) => decodeMessage({ orgId: org, - chatId: `chat-${org}`, + chatId: options.chat ?? `chat-${org}`, messageId, seq: options.seq ?? 1, author: @@ -91,25 +104,53 @@ const storeMessage = Effect.fn("test.storeMessage")(function* (row: KinMessage) ${row.kind}, ${row.body}, ${row.intent}, '[]', ${row.status}, ${row.createdAt})`; }); -// Records every enqueue result, so tests await the bridge's work instead of sleeping. +// Records every enqueue attempt and result. `settle` publishes a post the bridge ignores and waits +// until the bridge pulls it: catch-up and every earlier hub event are handled by then. const start = Effect.fn("test.start")(function* () { - const results = yield* Queue.unbounded<{ - readonly event: KinEvent; - readonly duplicate: boolean; - }>(); + const attempts: Array = []; + const results: Array<{ readonly event: KinEvent; readonly duplicate: boolean }> = []; + const pulled = yield* Queue.unbounded(); const queue = yield* KinEventQueue.KinEventQueue; + const hub = yield* Hub.KinChatHub; yield* Layer.build( ChatWake.layer.pipe( Layer.provide( - Layer.succeed(KinEventQueue.KinEventQueue, { - ...queue, - enqueue: (event) => - queue.enqueue(event).pipe(Effect.tap((result) => Queue.offer(results, result))), - }), + Layer.mergeAll( + Layer.succeed(KinEventQueue.KinEventQueue, { + ...queue, + enqueue: (event) => + Effect.sync(() => attempts.push(event)).pipe( + Effect.andThen(queue.enqueue(event)), + Effect.tap((result) => Effect.sync(() => results.push(result))), + ), + }), + Layer.succeed(Hub.KinChatHub, { + ...hub, + subscribeAll: hub.subscribeAll.pipe( + Effect.map( + Stream.tap((event) => + event.type === "message.posted" + ? Queue.offer(pulled, event.message.messageId) + : Effect.void, + ), + ), + ), + }), + ), ), ), ); - return results; + let settled = 0; + const settle = Effect.gen(function* () { + const id = `settle-${++settled}`; + yield* hub.publish({ + type: "message.posted", + orgId: KinOrgId.make("a"), + message: message("a", id, { agent: true }), + }); + while ((yield* Queue.take(pulled)) !== id); + }); + return { attempts, results, settle }; }); const storedEvents = Effect.fn("test.storedEvents")(function* () { @@ -121,24 +162,30 @@ const storedEvents = Effect.fn("test.storedEvents")(function* () { ); }); +const keys = (events: ReadonlyArray) => events.map((event) => event.dedupeKey); +const post = (org: string, messageId: string, options: Parameters[2] = {}) => + Effect.gen(function* () { + const hub = yield* Hub.KinChatHub; + yield* hub.publish({ + type: "message.posted", + orgId: KinOrgId.make(org), + message: message(org, messageId, options), + }); + }); + describe("ChatWake", () => { it.effect("wakes the lead once for each owner message and widget tap in its chat", () => Effect.gen(function* () { yield* seed("a"); - const hub = yield* Hub.KinChatHub; - const results = yield* start(); - const orgId = KinOrgId.make("a"); - yield* hub.publish({ type: "message.posted", orgId, message: message("a", "m1") }); - yield* hub.publish({ type: "message.posted", orgId, message: message("a", "m1") }); - yield* hub.publish({ - type: "message.posted", - orgId, - message: message("a", "tap", { seq: 2, tap: "approve" }), - }); - const [first, replay, tap] = yield* Queue.takeN(results, 3); - assert.strictEqual(first?.duplicate, false); - assert.strictEqual(replay?.duplicate, true); - assert.strictEqual(tap?.duplicate, false); + const { results, settle } = yield* start(); + yield* post("a", "m1"); + yield* post("a", "m1"); + yield* post("a", "tap", { seq: 2, tap: "approve" }); + yield* settle; + assert.deepStrictEqual( + results.map((result) => result.duplicate), + [false, true, false], + ); const stored = yield* storedEvents(); assert.deepStrictEqual( stored.map(({ event, priority }) => [event._tag, event.dedupeKey, priority]), @@ -158,36 +205,36 @@ describe("ChatWake", () => { }).pipe(Effect.provide(services)), ); - it.effect("never wakes a lead for its own posts or after retirement", () => + it.effect("never wakes a lead for its own posts or after retirement, live or on catch-up", () => Effect.gen(function* () { yield* seed("a"); yield* seed("b"); const sql = yield* SqlClient.SqlClient; yield* sql`UPDATE kin_agents SET retired_at = ${createdAt} WHERE agent_id = 'lead-b'`; - const hub = yield* Hub.KinChatHub; - const results = yield* start(); - yield* hub.publish({ - type: "message.posted", - orgId: KinOrgId.make("a"), - message: message("a", "reply", { agent: true }), - }); - yield* hub.publish({ - type: "message.posted", - orgId: KinOrgId.make("b"), - message: message("b", "to-retired"), - }); - yield* hub.publish({ - type: "message.posted", - orgId: KinOrgId.make("a"), - message: message("a", "sentinel", { seq: 2 }), - }); - // The stream is ordered, so the sentinel's result means the earlier posts were handled. - const result = yield* Queue.take(results); - assert.strictEqual(result.event.dedupeKey, "chat-message:sentinel:lead-a"); - assert.deepStrictEqual( - (yield* storedEvents()).map(({ event }) => event.dedupeKey), - ["chat-message:sentinel:lead-a"], - ); + yield* storeMessage(message("b", "missed-by-retired")); + const { attempts, settle } = yield* start(); + yield* post("a", "reply", { agent: true }); + // The bridge itself skips retired leads; the queue's own refusal is a second line. + yield* post("b", "to-retired", { seq: 2 }); + yield* post("a", "wake", { seq: 2 }); + yield* settle; + assert.deepStrictEqual(keys(attempts), ["chat-message:wake:lead-a"]); + assert.deepStrictEqual(keys((yield* storedEvents()).map(({ event }) => event)), [ + "chat-message:wake:lead-a", + ]); + }).pipe(Effect.provide(services)), + ); + + it.effect("never wakes a lead for group posts, live or on catch-up, until CHAT-11", () => + Effect.gen(function* () { + yield* seed("a"); + yield* seed("g", "team_group"); + yield* storeMessage(message("g", "missed-group")); + const { attempts, settle } = yield* start(); + yield* post("g", "group", { seq: 2 }); + yield* settle; + assert.deepStrictEqual(attempts, []); + assert.deepStrictEqual(yield* storedEvents(), []); }).pipe(Effect.provide(services)), ); @@ -197,22 +244,97 @@ describe("ChatWake", () => { yield* storeMessage(message("a", "answered", { seq: 1 })); yield* storeMessage(message("a", "lead-reply", { seq: 2, agent: true })); yield* storeMessage(message("a", "unanswered", { seq: 3 })); - const hub = yield* Hub.KinChatHub; - const results = yield* start(); - assert.strictEqual( - (yield* Queue.take(results)).event.dedupeKey, + const { results, settle } = yield* start(); + yield* post("a", "live", { seq: 4 }); + yield* settle; + assert.deepStrictEqual(keys(results.map((result) => result.event)), [ "chat-message:unanswered:lead-a", - ); - yield* hub.publish({ - type: "message.posted", - orgId: KinOrgId.make("a"), - message: message("a", "live", { seq: 4 }), - }); - assert.strictEqual((yield* Queue.take(results)).event.dedupeKey, "chat-message:live:lead-a"); + "chat-message:live:lead-a", + ]); + assert.deepStrictEqual(keys((yield* storedEvents()).map(({ event }) => event)).toSorted(), [ + "chat-message:live:lead-a", + "chat-message:unanswered:lead-a", + ]); + }).pipe(Effect.provide(services)), + ); + + it.effect("stores one event when catch-up and live delivery see the same message", () => + Effect.gen(function* () { + yield* seed("a"); + // Committed before catch-up reads, and published to the already subscribed bridge. + yield* storeMessage(message("a", "both")); + const { results, settle } = yield* start(); + yield* post("a", "both"); + yield* settle; assert.deepStrictEqual( - (yield* storedEvents()).map(({ event }) => event.dedupeKey).toSorted(), - ["chat-message:live:lead-a", "chat-message:unanswered:lead-a"], + results.map((result) => [result.event.dedupeKey, result.duplicate]), + [ + ["chat-message:both:lead-a", false], + ["chat-message:both:lead-a", true], + ], ); + assert.lengthOf(yield* storedEvents(), 1); }).pipe(Effect.provide(services)), ); + + it.effect("counts only posts a lead could answer toward the catch-up limit", () => + Effect.gen(function* () { + yield* seed("a"); + const sql = yield* SqlClient.SqlClient; + // A group the lead is in, and a retired lead's direct chat, each busier than the limit. + yield* sql`INSERT INTO kin_chats (chat_id, org_id, kind, last_seq, created_at) + VALUES ('group-a', 'a', 'team_group', 0, ${createdAt})`; + yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, agent_id, role, joined_at) + VALUES ('lead-group-member', 'a', 'group-a', 'agent', 'lead-a', 'member', ${createdAt})`; + yield* sql`INSERT INTO kin_agents (agent_id, org_id, display_name, role, owner_person_id, created_at, retired_at) + VALUES ('old-a', 'a', 'Old', 'lead', 'owner-a', ${createdAt}, ${createdAt})`; + yield* sql`INSERT INTO kin_chats (chat_id, org_id, kind, direct_key, last_seq, created_at) + VALUES ('old-chat', 'a', 'direct', 'direct-old', 0, ${createdAt})`; + yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, agent_id, role, joined_at) + VALUES ('old-member', 'a', 'old-chat', 'agent', 'old-a', 'member', ${createdAt})`; + yield* sql`INSERT INTO kin_leads (agent_id, org_id, name, level_since, models_json, worker_projects_json, owner_chat_id) + VALUES ('old-a', 'a', 'Old', 0, '{}', '[]', 'old-chat')`; + // Their ids sort above the direct post, so either one counted would push it out. + for (let seq = 1; seq <= 200; seq++) { + const n = String(seq).padStart(3, "0"); + yield* storeMessage(message("a", `z-group-${n}`, { seq, chat: "group-a" })); + yield* storeMessage(message("a", `y-retired-${n}`, { seq, chat: "old-chat" })); + } + yield* storeMessage(message("a", "a-direct")); + const { attempts, settle } = yield* start(); + yield* settle; + assert.deepStrictEqual(keys(attempts), ["chat-message:a-direct:lead-a"]); + }).pipe(Effect.provide(services)), + ); + + it.effect("limits catch-up per organization, so a busy one cannot starve another", () => + Effect.gen(function* () { + yield* seed("a"); + yield* seed("b"); + for (let seq = 1; seq <= 201; seq++) + yield* storeMessage(message("a", `m${String(seq).padStart(3, "0")}`, { seq })); + // Sorts below org a's ids, so a single global limit would drop it. + yield* storeMessage(message("b", "b-quiet")); + const { results, settle } = yield* start(); + yield* settle; + const woken = results.map((result) => result.event); + assert.strictEqual(woken.filter((event) => event.orgId === "a").length, 200); + assert.deepStrictEqual(keys(woken.filter((event) => event.orgId === "b")), [ + "chat-message:b-quiet:lead-b", + ]); + }).pipe(Effect.provide(services)), + ); + + it("keeps the every-organization chat stream away from tools and transports", () => { + // KinChatHub sits in KinServer.services, which the MCP toolkits receive. + const root = NodePath.resolve(import.meta.dirname, "../.."); + const readers = (NodeFS.readdirSync(root, { recursive: true }) as Array) + .filter((file) => file.endsWith(".ts") && !file.endsWith(".test.ts")) + .map((file) => file.split(NodePath.sep).join("/")) + .filter((file) => + /\bsubscribeAll\b/.test(NodeFS.readFileSync(NodePath.join(root, file), "utf8")), + ) + .toSorted(); + assert.deepStrictEqual(readers, ["kin/chat/KinChatHub.ts", "kin/lead/ChatWake.ts"]); + }); }); diff --git a/apps/server/src/kin/lead/ChatWake.ts b/apps/server/src/kin/lead/ChatWake.ts index 3a0b15ce460f9..2c962ed17877d 100644 --- a/apps/server/src/kin/lead/ChatWake.ts +++ b/apps/server/src/kin/lead/ChatWake.ts @@ -18,6 +18,7 @@ import * as Schema from "effect/Schema"; import * as Stream from "effect/Stream"; import * as SqlClient from "effect/sql/SqlClient"; +import { toPersistenceSqlError } from "../../persistence/Errors.ts"; import { forkParked } from "../../serverActivation.ts"; import { KinChatHub } from "../chat/KinChatHub.ts"; import { KinChatRepository } from "../chat/KinChatRepository.ts"; @@ -28,11 +29,12 @@ const decodeTap = Schema.decodeUnknownEffect( ); // Matches the resume expiry: older unanswered messages are not worth a wake-up after downtime. const CATCH_UP_WINDOW = { hours: 24 } as const; -const CATCH_UP_LIMIT = 200; +const CATCH_UP_LIMIT_PER_ORG = 200; /** * Turns committed human chat posts and widget taps into `chat.message` and `widget.action` * events for the lead the floor manager would wake: mentioned leads, else the chat's lead. + * Direct chats only: a lead cannot reply in a group until CHAT-11 delivers group grants. */ const make = Effect.gen(function* () { const sql = yield* SqlClient.SqlClient; @@ -47,10 +49,13 @@ const make = Effect.gen(function* () { const leads = yield* sql<{ agentId: string; memberId: string }>` SELECT l.agent_id AS "agentId", m.member_id AS "memberId" FROM kin_leads l JOIN kin_agents a ON a.org_id = l.org_id AND a.agent_id = l.agent_id AND a.retired_at IS NULL - JOIN kin_chat_members m ON m.org_id = l.org_id AND m.chat_id = ${message.chatId} + JOIN kin_chats c ON c.org_id = l.org_id AND c.chat_id = ${message.chatId} AND c.kind = 'direct' + JOIN kin_chat_members m ON m.org_id = l.org_id AND m.chat_id = c.chat_id AND m.principal_kind = 'agent' AND m.agent_id = l.agent_id AND m.left_at IS NULL WHERE l.org_id = ${message.orgId} - ORDER BY CASE a.role WHEN 'lead' THEN 0 ELSE 1 END, m.joined_at, l.agent_id`; + ORDER BY CASE a.role WHEN 'lead' THEN 0 ELSE 1 END, m.joined_at, l.agent_id`.pipe( + Effect.mapError(toPersistenceSqlError("KinChatWake.leads")), + ); const mentioned = leads.filter((lead) => message.mentions.some((memberId) => memberId === lead.memberId), ); @@ -103,30 +108,50 @@ const make = Effect.gen(function* () { ); // Messages posted while the server was down or Kin was off never reached the hub. - const catchUp = Effect.fn("KinChatWake.catchUp")( - function* () { - const since = DateTime.formatIso(DateTime.subtract(yield* DateTime.now, CATCH_UP_WINDOW)); - const rows = yield* sql<{ orgId: string; messageId: string; createdAt: string }>` - SELECT DISTINCT m.org_id AS "orgId", m.message_id AS "messageId", m.created_at AS "createdAt" + const catchUpOrg = Effect.fn("KinChatWake.catchUpOrg")( + function* (orgId: KinOrgId, since: string) { + const rows = yield* sql<{ messageId: string }>` + SELECT DISTINCT m.message_id AS "messageId", m.created_at AS "createdAt" FROM kin_leads l JOIN kin_agents a ON a.org_id = l.org_id AND a.agent_id = l.agent_id AND a.retired_at IS NULL JOIN kin_chat_members am ON am.org_id = l.org_id AND am.principal_kind = 'agent' AND am.agent_id = l.agent_id AND am.left_at IS NULL - JOIN kin_messages m ON m.org_id = am.org_id AND m.chat_id = am.chat_id - WHERE m.author_kind = 'human' AND m.status = 'posted' AND m.kind IN ('text', 'widget_action') + JOIN kin_chats c ON c.org_id = am.org_id AND c.chat_id = am.chat_id AND c.kind = 'direct' + JOIN kin_messages m ON m.org_id = c.org_id AND m.chat_id = c.chat_id + WHERE l.org_id = ${orgId} + AND m.author_kind = 'human' AND m.status = 'posted' AND m.kind IN ('text', 'widget_action') AND m.created_at > ${since} AND m.seq > COALESCE((SELECT MAX(x.seq) FROM kin_messages x WHERE x.org_id = m.org_id AND x.chat_id = m.chat_id AND x.author_kind = 'agent' AND x.author_agent_id = l.agent_id), 0) - ORDER BY m.created_at DESC, m.message_id DESC LIMIT ${CATCH_UP_LIMIT}`; + ORDER BY m.created_at DESC, m.message_id DESC LIMIT ${CATCH_UP_LIMIT_PER_ORG}`.pipe( + Effect.mapError(toPersistenceSqlError("KinChatWake.catchUpOrg")), + ); for (const row of rows) { const message = yield* repo.getMessage({ - orgId: KinOrgId.make(row.orgId), + orgId, messageId: KinMessageId.make(row.messageId), }); if (Option.isSome(message)) yield* wake(message.value); } }, + (effect, orgId) => + effect.pipe( + Effect.catchCause((cause) => + Effect.logError("Kin chat wake-up catch-up failed", { orgId, cause }), + ), + ), + ); + const catchUp = Effect.fn("KinChatWake.catchUp")( + function* () { + const since = DateTime.formatIso(DateTime.subtract(yield* DateTime.now, CATCH_UP_WINDOW)); + const orgs = yield* sql<{ orgId: string }>` + SELECT DISTINCT org_id AS "orgId" FROM kin_leads ORDER BY org_id`.pipe( + Effect.mapError(toPersistenceSqlError("KinChatWake.catchUp")), + ); + // Per organization, so one busy organization cannot use up another's catch-up. + for (const org of orgs) yield* catchUpOrg(KinOrgId.make(org.orgId), since); + }, Effect.catchCause((cause) => Effect.logError("Kin chat wake-up catch-up failed", { cause })), ); diff --git a/apps/server/src/kin/lead/WakeupRunner.test.ts b/apps/server/src/kin/lead/WakeupRunner.test.ts index 80f63989b53ff..5e1432d6bd7fb 100644 --- a/apps/server/src/kin/lead/WakeupRunner.test.ts +++ b/apps/server/src/kin/lead/WakeupRunner.test.ts @@ -14,6 +14,8 @@ import { KinWakeupId, KinEvent, KinAgentId, + KinChatId, + KinMessageId, KinPersonId, ThreadId, RunId, @@ -25,11 +27,15 @@ import { import * as OwnerCheck from "../triggers/ownerCheck.ts"; import * as ChatService from "../chat/KinChatService.ts"; import * as ChatHub from "../chat/KinChatHub.ts"; +import * as KinChatRepository from "../chat/KinChatRepository.ts"; +import * as Floor from "../floor/KinFloor.ts"; +import { FLOOR_GRANT_TTL_MS } from "../floor/FloorManager.ts"; import * as Context from "effect/Context"; import * as Deferred from "effect/Deferred"; import * as Effect from "effect/Effect"; import * as Fiber from "effect/Fiber"; import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; import * as Schema from "effect/Schema"; import * as SqlClient from "effect/sql/SqlClient"; import * as TestClock from "effect/testing/TestClock"; @@ -396,6 +402,67 @@ describe("WakeupRunner", () => { ]); }).pipe(Effect.provide(harness()), provideDeterministicTestRuntime), ); + it.effect("re-arms a lapsed direct-chat grant when the wake-up starts, for one reply only", () => + Effect.gen(function* () { + const entered = yield* Deferred.make(); + const hold = yield* Deferred.make(); + yield* Effect.gen(function* () { + yield* seed; + const sql = yield* SqlClient.SqlClient; + const repo = yield* KinChatRepository.KinChatRepository; + const floor = yield* Floor.KinFloor; + const at = "2026-11-08T00:00:00.000Z"; + yield* sql`INSERT INTO kin_chats (chat_id, org_id, kind, direct_key, last_seq, created_at) + VALUES ('direct', 'org', 'direct', 'owner:lead', 1, ${at})`; + yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, person_id, role, joined_at) + VALUES ('owner-member', 'org', 'direct', 'person', 'owner', 'owner', ${at})`; + yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, agent_id, role, joined_at) + VALUES ('lead-member', 'org', 'direct', 'agent', 'lead', 'member', ${at})`; + yield* sql`INSERT INTO kin_messages (message_id, org_id, chat_id, seq, author_kind, author_person_id, + author_member_id, author_role, kind, body, mentions_json, status, created_at) + VALUES ('hi', 'org', 'direct', 1, 'human', 'owner', 'owner-member', 'owner', 'text', 'hi', '[]', + 'posted', ${at})`; + const scope = { orgId, chatId: KinChatId.make("direct") }; + const chat = Option.getOrThrow(yield* repo.getChat(scope)); + const message = Option.getOrThrow( + yield* repo.getMessage({ orgId, messageId: KinMessageId.make("hi") }), + ); + yield* floor.open(message, chat); + // The post-time grant lapses while the server is down, before catch-up enqueues it. + yield* TestClock.adjust(FLOOR_GRANT_TTL_MS + 60_000); + yield* (yield* KinEventQueue.KinEventQueue).enqueue( + decodeEvent({ + _tag: "chat.message", + orgId, + agentId, + eventId: "catch-up-hi", + receivedAt: at, + dedupeKey: "chat-message:hi:lead", + provenance: { _tag: "human", personId: "owner", memberId: "owner-member" }, + chatId: "direct", + messageId: "hi", + }), + ); + const fiber = yield* run(); + yield* Deferred.await(entered); + const [lead] = yield* sql<{ thread_id: string }>`SELECT thread_id FROM kin_leads`; + const identity = yield* resolveAgent(ThreadId.make(lead!.thread_id)); + assert.isNotNull((yield* floor.authorize(identity, chat, "answer")).runId); + assert.include(yield* floor.authorize(identity, chat, "evidence").pipe(Effect.flip), { + reason: "floor_not_granted", + }); + yield* Deferred.succeed(hold, undefined); + yield* Fiber.join(fiber); + }).pipe( + Effect.provide( + Layer.mergeAll(Floor.layer, KinChatRepository.layer).pipe( + Layer.provideMerge(harness({ entered, hold })), + ), + ), + ); + }).pipe(provideDeterministicTestRuntime), + ); + it.effect("interrupts mid-wake-up without counting an attempt and admits the next claim", () => Effect.gen(function* () { const entered = yield* Deferred.make(); diff --git a/apps/server/src/kin/lead/WakeupRunner.ts b/apps/server/src/kin/lead/WakeupRunner.ts index d3315cbbec6b2..3ce44b3f43fc1 100644 --- a/apps/server/src/kin/lead/WakeupRunner.ts +++ b/apps/server/src/kin/lead/WakeupRunner.ts @@ -29,6 +29,7 @@ import * as ThreadManagementService from "../../orchestration-v2/ThreadManagemen import { toPersistenceSqlError } from "../../persistence/Errors.ts"; import * as ProjectService from "../../project/ProjectService.ts"; import * as KinIdentity from "../chat/KinIdentity.ts"; +import * as Floor from "../floor/KinFloor.ts"; import * as Writer from "../memory/MemoryWriter.ts"; import * as Memory from "../memory/Memory.ts"; import * as Routines from "../triggers/routines.ts"; @@ -113,6 +114,7 @@ const make = Effect.gen(function* () { const hooks = yield* Effect.serviceOption(KinWakeupHooks); const prompt = yield* KinLeadPrompt; const identity = yield* KinIdentity.KinIdentity; + const floor = yield* Floor.KinFloor; const registry = yield* KinLeadRegistry.KinLeadRegistry; const projects = yield* ProjectService.ProjectService; const launch = yield* ThreadLaunchService.ThreadLaunchService; @@ -499,6 +501,16 @@ const make = Effect.gen(function* () { yield* sql`SELECT 1 FROM kin_agents WHERE org_id = ${orgId} AND agent_id = ${agentId} AND retired_at IS NULL`; if (active === undefined) return yield* new KinWakeupError({ orgId, agentId, cause: "retired" }); + // The post-time grant may have lapsed while these events waited to be claimed. + yield* floor.renew({ + orgId, + agentId, + messageIds: events.flatMap((event) => + event._tag === "chat.message" || event._tag === "widget.action" + ? [event.messageId] + : [], + ), + }); yield* identity.registerAgentThread({ orgId, agentId, threadId }); yield* sql`UPDATE kin_leads SET thread_id = ${threadId} WHERE org_id = ${orgId} AND agent_id = ${agentId}`; yield* sql`UPDATE kin_wakeups SET thread_id = ${threadId}, model = ${modelSelection.model} @@ -760,4 +772,4 @@ const make = Effect.gen(function* () { return WakeupRunner.of({ runOnce, recover, start }); }); -export const layer = Layer.effect(WakeupRunner, make); +export const layer = Layer.effect(WakeupRunner, make).pipe(Layer.provide(Floor.layer)); diff --git a/docs/kin/specs/chat.md b/docs/kin/specs/chat.md index 3f823977d08bf..074c756676cd6 100644 --- a/docs/kin/specs/chat.md +++ b/docs/kin/specs/chat.md @@ -379,7 +379,7 @@ Kin serves these tools at **`/kin/mcp`**, alongside the existing T3 tools, never `kin_chat_post` accepts an optional `clientMessageId` retry key. Reusing it with identical content returns the stored row; changed content fails `not_allowed`. Omission creates a fresh post on each call. Bodies are nonblank, at most 16,000 characters, and contain no NUL; mentions are capped at 100. Reads are per-call, ascending after a non-negative safe-integer `afterSeq`, with a default limit of 50 and a maximum of 100, and preserve the viewer's suggestion visibility. No agent stream is exposed. -Task-card creation is server-only and unavailable through this toolkit. Updates require `widgetId` plus the expected `revision`; missing revision is refused and stale revision fails `widget_changed`. The anchor is immutable, and an agent can update only cards anchored by its own member. Neither trusted waiting APIs nor hub subscriptions are exposed. `approval` is refused by the service. `kin_floor_bid` is phase 2 and absent from the phase-1 toolkit. CHAT-9 keeps group grant tokens internal; direct-chat grants are implicit. CHAT-11 and the phase-2 floor-bid work must deliver group grants through the agent wake-up before exposing `floorGrant` in `kin_chat_post`. Until then, a mentioned agent in a group cannot reply. Grants expire after five minutes and are single-use. Trusted server notices (`KinChatService.notice`) bypass the floor and agent-notice quota; agent notices are classified from the running wake-up's stored events, never from a model-provided flag. Notice classification applies to the entire wake-up across all of the agent's chats, not only the destination chat. A batch containing chat events is treated as replies. +Task-card creation is server-only and unavailable through this toolkit. Updates require `widgetId` plus the expected `revision`; missing revision is refused and stale revision fails `widget_changed`. The anchor is immutable, and an agent can update only cards anchored by its own member. Neither trusted waiting APIs nor hub subscriptions are exposed. `approval` is refused by the service. `kin_floor_bid` is phase 2 and absent from the phase-1 toolkit. CHAT-9 keeps group grant tokens internal; direct-chat grants are implicit. CHAT-11 and the phase-2 floor-bid work must deliver group grants through the agent wake-up before exposing `floorGrant` in `kin_chat_post`. Until then, a mentioned agent in a group cannot reply. Grants expire after five minutes and are single-use. When a wake-up carrying the message that opened a direct-chat run starts, the runner gives the lead's unused grant on that run five more minutes (lead spec, `KinFloor.renew`); it never issues one. Trusted server notices (`KinChatService.notice`) bypass the floor and agent-notice quota; agent notices are classified from the running wake-up's stored events, never from a model-provided flag. Notice classification applies to the entire wake-up across all of the agent's chats, not only the destination chat. A batch containing chat events is treated as replies. ### Floor manager (plain code) diff --git a/docs/kin/specs/lead.md b/docs/kin/specs/lead.md index a90b0a2f59c07..fd9be7b9c7978 100644 --- a/docs/kin/specs/lead.md +++ b/docs/kin/specs/lead.md @@ -165,7 +165,9 @@ Events carry references, not bodies. The lead reads the message or payload throu | Executor finishes or a grant expires | `action.resolved` | approvals spec | | Stop switch turned off | `resume` | this spec | -`ChatWake` subscribes to every organization on `KinChatHub` and wakes mentioned leads, else the chat's first lead, as the floor manager does. Agent and system posts never wake a lead. Event ids derive from the message and lead, so a replay collapses. Posts made while the server was down never reach the hub, so on startup it re-enqueues human posts from the last 24 hours that came after the lead's last post in that chat. +`ChatWake` subscribes to every organization on `KinChatHub` and wakes mentioned leads, else the chat's first lead, as the floor manager does. It covers direct chats only, since a lead can't reply in a group until CHAT-11. Agent and system posts never wake a lead. Event ids derive from the message and lead, so a replay collapses. Posts made while the server was down never reach the hub, so on startup it re-enqueues, per organization, human posts from the last 24 hours that came after the lead's last post in that chat. `subscribeAll` is server-only: a source guard in `ChatWake.test.ts` keeps it out of tools and transports. + +The floor grant from a post lasts five minutes, and a queued wake-up can start later (catch-up, the stop switch, budget deferral). So when the runner launches a wake-up, `KinFloor.renew` gives five more minutes to the lead's unused grant on each open direct-chat run that one of its claimed messages opened. It never issues a grant: a newer human message has closed that run, and a reply has used the grant. All producers call one entry point: `KinEventQueue.enqueue(event)`. Nothing else may start a lead session. Scheduled tasks in particular must not launch a T3 thread with a lead prompt; the triggers spec routes their fires into `enqueue`. From 389caaf13e034eeb422697eca21f7fc328e31546 Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Mon, 9 Nov 2026 20:32:50 +0530 Subject: [PATCH 4/4] fix(kin): a renewed reply grant lasts until the wake-up's deadline A lead that reads memory before replying took longer than five minutes and had its reply refused. Also pins that a used grant is never re-armed. Co-Authored-By: Claude Opus 5.5 --- apps/server/src/kin/floor/KinFloor.ts | 5 ++++- apps/server/src/kin/lead/WakeupRunner.test.ts | 13 +++++++++++++ apps/server/src/kin/lead/WakeupRunner.ts | 11 +++++++++-- docs/kin/specs/chat.md | 2 +- docs/kin/specs/lead.md | 2 +- 5 files changed, 28 insertions(+), 5 deletions(-) diff --git a/apps/server/src/kin/floor/KinFloor.ts b/apps/server/src/kin/floor/KinFloor.ts index 7a1c9da29f4cb..4fc6d3a7cdd6e 100644 --- a/apps/server/src/kin/floor/KinFloor.ts +++ b/apps/server/src/kin/floor/KinFloor.ts @@ -73,11 +73,13 @@ export class KinFloor extends Context.Service< /** * Re-arms the agent's unused direct-chat grant on each open run one of `messageIds` opened, * so a wake-up that starts after the TTL can still reply once. It never issues a grant. + * `until` (the wake-up's own deadline) replaces the default TTL from now. */ readonly renew: (input: { readonly orgId: KinOrgId; readonly agentId: KinAgentId; readonly messageIds: ReadonlyArray; + readonly until?: number; }) => Effect.Effect; readonly authorize: ( identity: AgentIdentity, @@ -182,9 +184,10 @@ const make = Effect.gen(function* () { readonly orgId: KinOrgId; readonly agentId: KinAgentId; readonly messageIds: ReadonlyArray; + readonly until?: number; }) { if (input.messageIds.length === 0) return; - const expiresAt = (yield* Clock.currentTimeMillis) + FLOOR_GRANT_TTL_MS; + const expiresAt = input.until ?? (yield* Clock.currentTimeMillis) + FLOOR_GRANT_TTL_MS; // A new human message closes the run, and a reply consumes the grant, so neither re-arms. yield* sql`UPDATE kin_floor_grants SET expires_at = MAX(expires_at, ${expiresAt}) WHERE org_id = ${input.orgId} AND agent_id = ${input.agentId} AND consumed_at IS NULL diff --git a/apps/server/src/kin/lead/WakeupRunner.test.ts b/apps/server/src/kin/lead/WakeupRunner.test.ts index 5e1432d6bd7fb..d1f4316849df1 100644 --- a/apps/server/src/kin/lead/WakeupRunner.test.ts +++ b/apps/server/src/kin/lead/WakeupRunner.test.ts @@ -447,10 +447,23 @@ describe("WakeupRunner", () => { yield* Deferred.await(entered); const [lead] = yield* sql<{ thread_id: string }>`SELECT thread_id FROM kin_leads`; const identity = yield* resolveAgent(ThreadId.make(lead!.thread_id)); + // The renewed grant lasts as long as the wake-up, so a reply 10 minutes in still lands. + yield* TestClock.adjust("10 minutes"); assert.isNotNull((yield* floor.authorize(identity, chat, "answer")).runId); assert.include(yield* floor.authorize(identity, chat, "evidence").pipe(Effect.flip), { reason: "floor_not_granted", }); + // A used grant is never re-armed, whatever deadline is asked for. + const grantExpiry = sql<{ expires_at: number }>`SELECT expires_at FROM kin_floor_grants + WHERE org_id = ${orgId} AND agent_id = ${agentId} ORDER BY expires_at`; + const before = yield* grantExpiry; + yield* floor.renew({ + orgId, + agentId, + messageIds: [KinMessageId.make("hi")], + until: Number.MAX_SAFE_INTEGER, + }); + assert.deepStrictEqual(yield* grantExpiry, before); yield* Deferred.succeed(hold, undefined); yield* Fiber.join(fiber); }).pipe( diff --git a/apps/server/src/kin/lead/WakeupRunner.ts b/apps/server/src/kin/lead/WakeupRunner.ts index 3ce44b3f43fc1..b966d7b567d2b 100644 --- a/apps/server/src/kin/lead/WakeupRunner.ts +++ b/apps/server/src/kin/lead/WakeupRunner.ts @@ -43,6 +43,8 @@ import { PAUSE_POLL_INTERVAL_MS } from "./KinStop.ts"; import { isOrgPaused } from "./orgState.ts"; import { KinPromotion } from "../levels/Promotion.ts"; +/** How long one wake-up may run before it is interrupted. */ +const WAKEUP_DEADLINE_MS = 900_000; const ownerCheckDispatcherReady = false; export class KinWakeupError extends Schema.TaggedError()("KinWakeupError", { @@ -189,7 +191,10 @@ const make = Effect.gen(function* () { if (row.threadId === null || row.runId === null) return; const threadId = row.threadId; const runId = row.runId; - const remaining = Math.max(0, row.startedAt + 900_000 - (yield* Clock.currentTimeMillis)); + const remaining = Math.max( + 0, + row.startedAt + WAKEUP_DEADLINE_MS - (yield* Clock.currentTimeMillis), + ); const result = yield* threads.waitForThread({ projectId, threadId: row.threadId, @@ -501,10 +506,12 @@ const make = Effect.gen(function* () { yield* sql`SELECT 1 FROM kin_agents WHERE org_id = ${orgId} AND agent_id = ${agentId} AND retired_at IS NULL`; if (active === undefined) return yield* new KinWakeupError({ orgId, agentId, cause: "retired" }); - // The post-time grant may have lapsed while these events waited to be claimed. + // The post-time grant may have lapsed while these events waited to be claimed; + // it now lasts as long as the wake-up may run, so a slow first reply still lands. yield* floor.renew({ orgId, agentId, + until: row.startedAt + WAKEUP_DEADLINE_MS, messageIds: events.flatMap((event) => event._tag === "chat.message" || event._tag === "widget.action" ? [event.messageId] diff --git a/docs/kin/specs/chat.md b/docs/kin/specs/chat.md index 074c756676cd6..8fcf55977c74c 100644 --- a/docs/kin/specs/chat.md +++ b/docs/kin/specs/chat.md @@ -379,7 +379,7 @@ Kin serves these tools at **`/kin/mcp`**, alongside the existing T3 tools, never `kin_chat_post` accepts an optional `clientMessageId` retry key. Reusing it with identical content returns the stored row; changed content fails `not_allowed`. Omission creates a fresh post on each call. Bodies are nonblank, at most 16,000 characters, and contain no NUL; mentions are capped at 100. Reads are per-call, ascending after a non-negative safe-integer `afterSeq`, with a default limit of 50 and a maximum of 100, and preserve the viewer's suggestion visibility. No agent stream is exposed. -Task-card creation is server-only and unavailable through this toolkit. Updates require `widgetId` plus the expected `revision`; missing revision is refused and stale revision fails `widget_changed`. The anchor is immutable, and an agent can update only cards anchored by its own member. Neither trusted waiting APIs nor hub subscriptions are exposed. `approval` is refused by the service. `kin_floor_bid` is phase 2 and absent from the phase-1 toolkit. CHAT-9 keeps group grant tokens internal; direct-chat grants are implicit. CHAT-11 and the phase-2 floor-bid work must deliver group grants through the agent wake-up before exposing `floorGrant` in `kin_chat_post`. Until then, a mentioned agent in a group cannot reply. Grants expire after five minutes and are single-use. When a wake-up carrying the message that opened a direct-chat run starts, the runner gives the lead's unused grant on that run five more minutes (lead spec, `KinFloor.renew`); it never issues one. Trusted server notices (`KinChatService.notice`) bypass the floor and agent-notice quota; agent notices are classified from the running wake-up's stored events, never from a model-provided flag. Notice classification applies to the entire wake-up across all of the agent's chats, not only the destination chat. A batch containing chat events is treated as replies. +Task-card creation is server-only and unavailable through this toolkit. Updates require `widgetId` plus the expected `revision`; missing revision is refused and stale revision fails `widget_changed`. The anchor is immutable, and an agent can update only cards anchored by its own member. Neither trusted waiting APIs nor hub subscriptions are exposed. `approval` is refused by the service. `kin_floor_bid` is phase 2 and absent from the phase-1 toolkit. CHAT-9 keeps group grant tokens internal; direct-chat grants are implicit. CHAT-11 and the phase-2 floor-bid work must deliver group grants through the agent wake-up before exposing `floorGrant` in `kin_chat_post`. Until then, a mentioned agent in a group cannot reply. Grants expire after five minutes and are single-use. When a wake-up carrying the message that opened a direct-chat run starts, the runner extends the lead's unused grant on that run to the wake-up's deadline (lead spec, `KinFloor.renew`); it never issues one. Trusted server notices (`KinChatService.notice`) bypass the floor and agent-notice quota; agent notices are classified from the running wake-up's stored events, never from a model-provided flag. Notice classification applies to the entire wake-up across all of the agent's chats, not only the destination chat. A batch containing chat events is treated as replies. ### Floor manager (plain code) diff --git a/docs/kin/specs/lead.md b/docs/kin/specs/lead.md index fd9be7b9c7978..50cc1804ed27e 100644 --- a/docs/kin/specs/lead.md +++ b/docs/kin/specs/lead.md @@ -167,7 +167,7 @@ Events carry references, not bodies. The lead reads the message or payload throu `ChatWake` subscribes to every organization on `KinChatHub` and wakes mentioned leads, else the chat's first lead, as the floor manager does. It covers direct chats only, since a lead can't reply in a group until CHAT-11. Agent and system posts never wake a lead. Event ids derive from the message and lead, so a replay collapses. Posts made while the server was down never reach the hub, so on startup it re-enqueues, per organization, human posts from the last 24 hours that came after the lead's last post in that chat. `subscribeAll` is server-only: a source guard in `ChatWake.test.ts` keeps it out of tools and transports. -The floor grant from a post lasts five minutes, and a queued wake-up can start later (catch-up, the stop switch, budget deferral). So when the runner launches a wake-up, `KinFloor.renew` gives five more minutes to the lead's unused grant on each open direct-chat run that one of its claimed messages opened. It never issues a grant: a newer human message has closed that run, and a reply has used the grant. +The floor grant from a post lasts five minutes, and a queued wake-up can start later (catch-up, the stop switch, budget deferral). So when the runner launches a wake-up, `KinFloor.renew` extends the lead's unused grant, on each open direct-chat run that one of its claimed messages opened, to the wake-up's own 15-minute deadline, so a lead that reads memory before replying isn't refused. It never issues a grant: a newer human message has closed that run, and a reply has used the grant. All producers call one entry point: `KinEventQueue.enqueue(event)`. Nothing else may start a lead session. Scheduled tasks in particular must not launch a T3 thread with a lead prompt; the triggers spec routes their fires into `enqueue`.