diff --git a/apps/server/src/kin/chat/KinChatService.ts b/apps/server/src/kin/chat/KinChatService.ts index 9ddf482ff10a7..5170346f48f27 100644 --- a/apps/server/src/kin/chat/KinChatService.ts +++ b/apps/server/src/kin/chat/KinChatService.ts @@ -49,6 +49,7 @@ import * as SqlError from "effect/sql/SqlError"; import * as SecureRandom from "effect/crypto/SecureRandom"; import { toPersistenceSqlError } from "../../persistence/Errors.ts"; import { validateState } from "../widgets/registry.ts"; +import { deferralCardActions, deferralCardActionsReady } from "../widgets/deferralCard.ts"; import * as Hub from "./KinChatHub.ts"; import * as Repository from "./KinChatRepository.ts"; import type { AgentIdentity, PersonIdentity } from "./KinIdentity.ts"; @@ -949,7 +950,11 @@ const make = Effect.gen(function* () { reason: "use_approvals", message: "Use the signed approvals service.", }); - if (input.type === "owner_check" || (input.type === "task" && input.widgetId === undefined)) + if ( + input.type === "owner_check" || + input.type === "deferral" || + (input.type === "task" && input.widgetId === undefined) + ) return yield* notAllowed; let state = yield* validateState(input.type, input.state); let widget: KinWidget; @@ -1088,6 +1093,14 @@ const make = Effect.gen(function* () { ) return yield* invalidState; } + if (widget.type === "deferral") { + if (member.role !== "owner") return yield* notAllowed; + if ( + !deferralCardActionsReady || + !deferralCardActions.some((action) => action === request.actionId) + ) + return yield* notAllowed; + } const body = yield* encodeAction({ widgetId: request.widgetId, revision: request.revision, diff --git a/apps/server/src/kin/lead/LeadMemory.test.ts b/apps/server/src/kin/lead/LeadMemory.test.ts index b9ece593335c8..01541b81f2a3a 100644 --- a/apps/server/src/kin/lead/LeadMemory.test.ts +++ b/apps/server/src/kin/lead/LeadMemory.test.ts @@ -481,7 +481,7 @@ it.live( .pipe(Effect.flip)).reason, "not_found", ); - for (const due of ["bad", "2026-02-30", "2026-11-13T09:00:00"]) + for (const due of ["bad", "2026-02-30", "2026-11-13T09:00:00", "1969-12-31", "0000-01-01"]) assert.strictEqual( (yield* decodeDefer({ ...deferred, due }).pipe(Effect.result))._tag, "Failure", diff --git a/apps/server/src/kin/lead/LeadMemory.ts b/apps/server/src/kin/lead/LeadMemory.ts index 9c98977df9f4f..78bb082da6bce 100644 --- a/apps/server/src/kin/lead/LeadMemory.ts +++ b/apps/server/src/kin/lead/LeadMemory.ts @@ -35,6 +35,9 @@ const date = Schema.String.check( expected: "a date or timestamp with explicit offset", }), ); +const deferDue = date.check( + Schema.makeFilter((value) => /^20\d\d-/.test(value), { expected: "a date in 2000-2099" }), +); const itemId = KinMemoryItemId.check(Schema.isPattern(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,199}$/)); export const SearchInput = Schema.Struct({ kind: Schema.optional(MemoryItemFrontMatter.fields.kind), @@ -65,7 +68,7 @@ export const WriteInput = Schema.Struct({ export const DeferInput = Schema.Struct({ itemId: Schema.optional(itemId), what: TrimmedNonEmptyString.check(Schema.isMaxLength(8000)), - due: date, + due: deferDue, onDue: Schema.Literals(["remind", "start", "ask", "chase"]), chatId: KinChatId, sourceEventId: TrimmedNonEmptyString, diff --git a/apps/server/src/kin/lead/layer.ts b/apps/server/src/kin/lead/layer.ts index 208f96ba6f7fb..685c2742aa7d8 100644 --- a/apps/server/src/kin/lead/layer.ts +++ b/apps/server/src/kin/lead/layer.ts @@ -4,6 +4,7 @@ import * as OwnerCheck from "../triggers/ownerCheck.ts"; import * as TriggerScheduler from "../triggers/KinTriggerScheduler.ts"; import * as TriggerStore from "../triggers/KinTriggerStore.ts"; import * as TriggerInbox from "../triggers/KinTriggerInbox.ts"; +import * as TriggerService from "../triggers/KinTriggerService.ts"; import { forkParked } from "../../serverActivation.ts"; import { KinOrgId, KinChatId, KinMessageId } from "@t3tools/contracts"; import * as SecureRandom from "effect/crypto/SecureRandom"; @@ -126,6 +127,12 @@ const withServices = (entry: Layer.Layer) => }), ).pipe(Layer.provide(KinChatRepository.layer)), ), + Layer.provide( + TriggerService.syncHooksLayer.pipe( + Layer.provide(TriggerService.layer), + Layer.provide(KinChatRepository.layer), + ), + ), Layer.provide(KinPersistence.layer), ); diff --git a/apps/server/src/kin/memory/Memory.ts b/apps/server/src/kin/memory/Memory.ts index d8aafb19a722a..cc6ca4aedc0cc 100644 --- a/apps/server/src/kin/memory/Memory.ts +++ b/apps/server/src/kin/memory/Memory.ts @@ -129,6 +129,19 @@ export class MemoryRecoveryHooks extends Context.Service< } >()("t3/kin/memory/Memory/MemoryRecoveryHooks") {} +export interface MemorySyncSnapshot { + readonly head: string; + readonly items: ReadonlyArray; + readonly duplicateIds: ReadonlySet; +} + +/** Sees every loaded snapshot and owns its own once-per-head, retry and failure handling. */ +export class MemorySyncHooks extends Context.Reference<{ + readonly syncItems: (orgId: KinOrgId, snapshot: MemorySyncSnapshot) => Effect.Effect; +}>("t3/kin/memory/Memory/MemorySyncHooks", { + defaultValue: () => ({ syncItems: () => Effect.void }), +}) {} + export class Memory extends Context.Service< Memory, { @@ -185,9 +198,7 @@ const folders = ["objectives", "commitments", "deferrals", "decisions", "people" const maxBlobBytes = 256 * 1024; -interface Snapshot { - readonly head: string; - readonly items: ReadonlyArray; +interface Snapshot extends MemorySyncSnapshot { readonly files: ReadonlyMap; index?: string; } @@ -218,6 +229,8 @@ const make = Effect.gen(function* () { const path = yield* Path.Path; const sql = yield* SqlClient.SqlClient; const writerLocks = new Map(); + const pinnedHeads = new Map(); + const hooks = yield* MemorySyncHooks; const withWriterLock = (orgId: KinOrgId, effect: Effect.Effect) => { let lock = writerLocks.get(orgId); if (!lock) { @@ -281,6 +294,9 @@ const make = Effect.gen(function* () { operation: "record", reason: "Anchor changed", }); + // The front-matter cache follows commits to the default branch. + if (branch === (config.defaultBranch ?? "main") && pinnedHeads.get(orgId) === previous) + pinnedHeads.set(orgId, head); }), ) .pipe( @@ -297,7 +313,6 @@ const make = Effect.gen(function* () { }); const cache = yield* MemoryCache.MemoryCache; const locks = new Map(); - const pinnedHeads = new Map(); const initializedCheckouts = new Set(); const duplicateWarnings = new Map>(); const snapshots = new Map(); @@ -530,7 +545,10 @@ const make = Effect.gen(function* () { return { writer: paths.writer, read: paths.read }; }); - const load = Effect.fn("Memory.load")(function* (orgId: KinOrgId, force = false) { + const loadSnapshot = Effect.fn("Memory.loadSnapshot")(function* ( + orgId: KinOrgId, + force: boolean, + ) { const paths = yield* pathsFor(orgId); const pinned = pinnedHeads.get(orgId); if (pinned === undefined) yield* validateWriter(orgId, paths, false); @@ -693,6 +711,7 @@ const make = Effect.gen(function* () { head, items, files, + duplicateIds, ...(previous?.head === head && previous.index !== undefined ? { index: previous.index } : {}), }; snapshots.set(orgId, snapshot); @@ -702,6 +721,11 @@ const make = Effect.gen(function* () { } return snapshot; }); + const load = Effect.fn("Memory.load")(function* (orgId: KinOrgId, force = false) { + const snapshot = yield* loadSnapshot(orgId, force); + yield* hooks.syncItems(orgId, snapshot); + return snapshot; + }); const query = Effect.fn("Memory.query")(function* (orgId: KinOrgId, q: MemoryQuery) { for (const value of [q.dueBefore, q.dueAfter]) { diff --git a/apps/server/src/kin/memory/MemoryWriter.test.ts b/apps/server/src/kin/memory/MemoryWriter.test.ts index e30d07c199428..13f18b2810bd3 100644 --- a/apps/server/src/kin/memory/MemoryWriter.test.ts +++ b/apps/server/src/kin/memory/MemoryWriter.test.ts @@ -3,7 +3,12 @@ import { memoryGit } from "./git.ts"; import * as NodeZlib from "node:zlib"; import * as NodeServices from "@effect/platform-node/NodeServices"; import { expect, it } from "@effect/vitest"; -import { KinAgentId, KinOrgId, VcsProcessSpawnError } from "@t3tools/contracts"; +import { + KinAgentId, + KinOrgId, + type MemoryItemHead, + VcsProcessSpawnError, +} from "@t3tools/contracts"; import * as Effect from "effect/Effect"; import * as FileSystem from "effect/FileSystem"; import * as Layer from "effect/Layer"; @@ -58,6 +63,9 @@ it.live.each([ "review-null", "credentials", "read-during-record", + "deferral-card-remind", + "deferral-plain-remind", + "deferral-card-other-item", "H3-packed-ref", "M1-unanchored", "M2-nondescendant", @@ -120,6 +128,10 @@ it.live.each([ }), ); } + if (scenario.startsWith("deferral-")) { + yield* fs.makeDirectory(`${source}/deferrals`); + yield* fs.writeFileString(`${source}/deferrals/def-001.md`, fixtureItem()); + } if (scenario === "B5-journal" || scenario === "P4-journal") { yield* fs.makeDirectory(`${source}/journal/2026`, { recursive: true }); yield* fs.writeFile( @@ -207,9 +219,18 @@ it.live.each([ credentialHelper: "fixture-server-helper", repositories: [{ orgId, repoUrl: remote, path: "state" }], }); + const synced: Array> = []; const memoryLayer = Memory.layer.pipe( Layer.provide(config), Layer.provide(Layer.succeed(Memory.MemoryRecoveryHooks, { notify: () => Effect.void })), + Layer.provide( + Layer.succeed(Memory.MemorySyncHooks, { + syncItems: (_org, snapshot) => + Effect.sync(() => { + synced.push(snapshot.items.map(({ head }) => head)); + }), + }), + ), ); const hooks = Layer.succeed(Writer.MemoryWriterHooks, { notify: Effect.fn("Test.notice")((notice) => @@ -233,7 +254,8 @@ it.live.each([ level: scenario === "conflict" || scenario === "B5-journal" || - scenario === "read-during-record" + scenario === "read-during-record" || + scenario.startsWith("deferral-") ? "L1" : "L0", timeZone: "Asia/Kolkata", @@ -258,11 +280,22 @@ it.live.each([ itemId: scenario === "owner-other-item-keep" ? "other-item" : "def-001", action: scenario === "owner-drop-keep" ? "drop" : "keep", } - : { - saidBy: "fixture-owner", - trust: "owner", - source: "fixture-owner-message", - }, + : scenario === "deferral-card-remind" || + scenario === "deferral-card-other-item" + ? { + saidBy: "fixture-owner", + trust: "owner", + source: "fixture-owner-message", + kind: "deferral_card", + itemId: + scenario === "deferral-card-other-item" ? "other-item" : "def-001", + action: "remind", + } + : { + saidBy: "fixture-owner", + trust: "owner", + source: "fixture-owner-message", + }, ], [ "member", @@ -609,6 +642,37 @@ it.live.each([ ).toBe("Success"); return; } + if (scenario === "deferral-plain-remind" || scenario === "deferral-card-other-item") { + const result = yield* writer + .stage(orgId, "wake1", { + path: "deferrals/def-001.md", + content: fixtureItem({ on_due: "remind" }), + sourceEventId: "owner", + }) + .pipe(Effect.result); + expect(result._tag === "Failure" && result.failure._tag).toBe("MemoryConflict"); + return; + } + if (scenario === "deferral-card-remind") { + const stage = (onDue: string) => + writer + .stage(orgId, "wake1", { + path: "deferrals/def-001.md", + content: fixtureItem({ on_due: onDue }), + sourceEventId: "owner", + }) + .pipe(Effect.result); + const forged = yield* stage("ask"); + expect(forged._tag === "Failure" && forged.failure._tag).toBe("MemoryConflict"); + expect((yield* stage("remind"))._tag).toBe("Success"); + const committed = yield* writer.commitWakeup(orgId, "wake1", "completed"); + expect( + yield* git(paths.writer, ["show", `${committed.commit}:deferrals/def-001.md`]), + ).toContain("on_due: remind"); + const last = synced.at(-1)?.find((item) => item.id === "def-001"); + expect(last?.on_due).toBe("remind"); + return; + } if (scenario.endsWith("-keep")) { const content = fixtureItem({ kind: "claim", diff --git a/apps/server/src/kin/memory/MemoryWriter.ts b/apps/server/src/kin/memory/MemoryWriter.ts index 1a00cc70a83fc..6285503d6004a 100644 --- a/apps/server/src/kin/memory/MemoryWriter.ts +++ b/apps/server/src/kin/memory/MemoryWriter.ts @@ -47,6 +47,7 @@ export interface WakeupContext extends JournalContext { readonly itemId: string; readonly action: "keep" | "update" | "drop"; } + | { readonly kind: "deferral_card"; readonly itemId: string; readonly action: "remind" } ) >; } @@ -532,10 +533,18 @@ const make = Effect.gen(function* () { ) mutable.add("review_by"); if ( - Object.entries(item).some( - ([key, value]) => + source.kind === "deferral_card" && + source.itemId === item.id && + item.kind === "deferral" && + fm.on_due === "remind" + ) + mutable.add("on_due"); + const existing = new Map(Object.entries(item)); + if ( + [...new Set([...existing.keys(), ...proposed.keys()])].some( + (key) => !mutable.has(key) && - JSON.stringify(value) !== JSON.stringify(proposed.get(key)), + JSON.stringify(existing.get(key)) !== JSON.stringify(proposed.get(key)), ) ) return yield* new MemoryConflict({ existingId: item.id }); @@ -804,6 +813,16 @@ const make = Effect.gen(function* () { recorded, ]); yield* memory.record(orgId, branch, recorded, commit); + // Arms deferrals from the commit now, not at the next wake-up. + if (branch === (config.defaultBranch ?? "main")) + yield* memory.rebuildCache(orgId).pipe( + Effect.catch((error) => + Effect.logWarning("Could not refresh memory cache after commit", { + orgId, + errorTag: error._tag, + }), + ), + ); yield* push(commit); return { commit }; }), diff --git a/apps/server/src/kin/persistence/KinMigrations.test.ts b/apps/server/src/kin/persistence/KinMigrations.test.ts index 98163746ceca1..0877625fa90a5 100644 --- a/apps/server/src/kin/persistence/KinMigrations.test.ts +++ b/apps/server/src/kin/persistence/KinMigrations.test.ts @@ -21,6 +21,7 @@ const tableNames = [ "kin_chat_members", "kin_chats", "kin_cursor", + "kin_deferral_runs", "kin_events", "kin_floor_grants", "kin_floor_notices", @@ -108,6 +109,7 @@ describe("Kin migrations", () => { { migration_id: 13, name: "Routines" }, { migration_id: 14, name: "LeadToolCalls" }, { migration_id: 15, name: "AuthSessionKeys" }, + { migration_id: 16, name: "DeferralRuns" }, ]); assert.deepStrictEqual( upstreamBefore.map((row) => [row.migration_id, row.name] as const), @@ -169,6 +171,7 @@ describe("Kin migrations", () => { { migration_id: 13, name: "Routines" }, { migration_id: 14, name: "LeadToolCalls" }, { migration_id: 15, name: "AuthSessionKeys" }, + { migration_id: 16, name: "DeferralRuns" }, ]); assert.deepStrictEqual(yield* upstreamHistory, upstreamBefore); assert.deepStrictEqual(yield* sql`SELECT * FROM kin_orgs`, [ @@ -255,6 +258,7 @@ describe("Kin migrations", () => { [13, "Routines"], [14, "LeadToolCalls"], [15, "AuthSessionKeys"], + [16, "DeferralRuns"], ]); const before = yield* kinSchema; assert.deepStrictEqual( @@ -283,6 +287,7 @@ describe("Kin migrations", () => { yield* sql`DROP INDEX idx_kin_messages_changes`; yield* sql`ALTER TABLE kin_messages DROP COLUMN change_seq`; yield* sql`ALTER TABLE kin_chats DROP COLUMN change_seq`; + yield* sql`DROP TABLE kin_deferral_runs`; yield* sql`DROP TABLE kin_auth_key_repairs`; yield* sql`DROP TABLE kin_auth_session_keys`; yield* sql`DROP TABLE kin_judge_log`; @@ -317,6 +322,7 @@ describe("Kin migrations", () => { [13, "Routines"], [14, "LeadToolCalls"], [15, "AuthSessionKeys"], + [16, "DeferralRuns"], ]); assert.deepStrictEqual( yield* sql`SELECT member_id FROM kin_chat_members WHERE org_id = 'org' ORDER BY member_id`, @@ -357,6 +363,7 @@ describe("Kin migrations", () => { { migration_id: 13, name: "Routines" }, { migration_id: 14, name: "LeadToolCalls" }, { migration_id: 15, name: "AuthSessionKeys" }, + { migration_id: 16, name: "DeferralRuns" }, ]); assert.deepStrictEqual(yield* runKinMigrations(), []); assert.deepStrictEqual(yield* runMigrations(), []); diff --git a/apps/server/src/kin/persistence/KinMigrations.ts b/apps/server/src/kin/persistence/KinMigrations.ts index 47b195065a1c1..f93768bc7945a 100644 --- a/apps/server/src/kin/persistence/KinMigrations.ts +++ b/apps/server/src/kin/persistence/KinMigrations.ts @@ -18,6 +18,7 @@ import SecretAllow from "./migrations/K012_SecretAllow.ts"; import Routines from "./migrations/K013_Routines.ts"; import LeadToolCalls from "./migrations/K014_LeadToolCalls.ts"; import AuthSessionKeys from "./migrations/K015_AuthSessionKeys.ts"; +import DeferralRuns from "./migrations/K016_DeferralRuns.ts"; const run = Migrator.make({}); const loader = Migrator.fromRecord({ @@ -36,6 +37,7 @@ const loader = Migrator.fromRecord({ "13_Routines": Routines, "14_LeadToolCalls": LeadToolCalls, "15_AuthSessionKeys": AuthSessionKeys, + "16_DeferralRuns": DeferralRuns, }); export const runKinMigrations = Effect.fn("KinMigrations.run")(function* () { diff --git a/apps/server/src/kin/persistence/migrations/K016_DeferralRuns.ts b/apps/server/src/kin/persistence/migrations/K016_DeferralRuns.ts new file mode 100644 index 0000000000000..f91ae1f6fbea4 --- /dev/null +++ b/apps/server/src/kin/persistence/migrations/K016_DeferralRuns.ts @@ -0,0 +1,17 @@ +import * as Effect from "effect/Effect"; +import * as SqlClient from "effect/sql/SqlClient"; + +export default Effect.gen(function* () { + const sql = yield* SqlClient.SqlClient; + // TRIG-7 writes armed/disarmed; the due flow (TRIG-8) owns the remaining states. + yield* sql`CREATE TABLE kin_deferral_runs ( + org_id TEXT NOT NULL REFERENCES kin_orgs(org_id), + item_id TEXT NOT NULL, + state TEXT NOT NULL, + due_at INTEGER CHECK (due_at IS NULL OR typeof(due_at) = 'integer'), + on_due TEXT NOT NULL CHECK (on_due IN ('remind', 'start', 'ask', 'chase')), + snapshot_json TEXT NOT NULL, + updated_at INTEGER NOT NULL CHECK (typeof(updated_at) = 'integer'), + PRIMARY KEY (org_id, item_id) + )`; +}); diff --git a/apps/server/src/kin/triggers/KinTriggerService.test.ts b/apps/server/src/kin/triggers/KinTriggerService.test.ts new file mode 100644 index 0000000000000..07fe4e79dee00 --- /dev/null +++ b/apps/server/src/kin/triggers/KinTriggerService.test.ts @@ -0,0 +1,325 @@ +import { assert, it } from "@effect/vitest"; +import { + KinChatId, + KinDeferralCard, + KinMemoryItemId, + KinOrgId, + KinPersonId, + KinWidgetId, + type MemoryItemHead, +} from "@t3tools/contracts"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; +import * as SqlClient from "effect/sql/SqlClient"; +import * as TestClock from "effect/testing/TestClock"; + +import * as Sqlite from "../../persistence/Sqlite.ts"; +import * as Chat from "../chat/KinChatService.ts"; +import * as Hub from "../chat/KinChatHub.ts"; +import * as Repository from "../chat/KinChatRepository.ts"; +import * as JudgeShadow from "../floor/JudgeShadow.ts"; +import * as Memory from "../memory/Memory.ts"; +import * as Persistence from "../persistence/KinPersistence.ts"; +import * as TriggerService from "./KinTriggerService.ts"; +import { item, orgId, otherOrg, seed } from "./routines.testkit.ts"; + +const decodeCard = Schema.decodeSync(Schema.fromJsonString(KinDeferralCard)); +const now = Date.parse("2026-11-09T09:00:00.000Z"); +const due = "2026-11-13T09:00+05:30"; +const dueAt = Date.parse("2026-11-13T03:30:00.000Z"); + +const layer = TriggerService.syncHooksLayer.pipe( + Layer.provideMerge(TriggerService.layer), + Layer.provideMerge( + Chat.layer.pipe(Layer.provide(JudgeShadow.layerOff), Layer.provideMerge(Hub.layer)), + ), + Layer.provideMerge(Repository.layer), + Layer.provideMerge(Persistence.layer.pipe(Layer.provideMerge(Sqlite.layerMemory))), +); + +const deferral = (overrides: Partial = {}) => + item("def-1", { + kind: "deferral", + path: "deferrals/def-1.md", + due, + on_due: "start", + chat: KinChatId.make(`chat-${overrides.orgId ?? orgId}`), + ...overrides, + }); + +const setup = Effect.fn("test.deferralSetup")(function* () { + yield* seed(); + const sql = yield* SqlClient.SqlClient; + yield* sql`INSERT INTO kin_trigger_settings VALUES (${orgId}, 'Asia/Kolkata', '08:30', '18:30', '03:00', 0, 1, '09:00', '{"from":"21:00","to":"08:00"}')`; + yield* TestClock.setTime(now); + return { sql, service: yield* TriggerService.KinTriggerService }; +}); + +const triggers = Effect.fn("test.deferralTriggers")(function* (org: string) { + const sql = yield* SqlClient.SqlClient; + return yield* sql<{ + id: string; + enabled: number; + nextRunAt: number | null; + updatedAt: number; + }>`SELECT trigger_id AS id, enabled, next_run_at AS "nextRunAt", updated_at AS "updatedAt" + FROM kin_triggers WHERE org_id = ${org} ORDER BY trigger_id`; +}); + +const card = Effect.fn("test.deferralCard")(function* (org: string) { + const sql = yield* SqlClient.SqlClient; + const rows = yield* sql<{ + revision: number; + state: string; + closedAt: string | null; + }>`SELECT revision, state_json AS state, closed_at AS "closedAt" FROM kin_widgets + WHERE org_id = ${org} AND type = 'deferral' ORDER BY widget_id`; + return rows.map((row) => ({ ...row, state: decodeCard(row.state) })); +}); + +it.effect("arms from front matter, re-arms on edits, and re-syncs without writes", () => + Effect.gen(function* () { + const { sql, service } = yield* setup(); + assert.equal(yield* service.syncItem(deferral()), "armed"); + const armed = yield* triggers(orgId); + assert.deepEqual( + armed.map(({ id, enabled, nextRunAt }) => [id, enabled, nextRunAt]), + [ + ["deferral:def-1:due", 1, dueAt], + ["deferral:def-1:heads_up", 1, dueAt - 30 * 60_000], + ], + ); + const [posted] = yield* card(orgId); + assert.equal(posted?.state.text, "Deferred to Fri 13 Nov, 9:00. I'll start then."); + const [message] = yield* sql<{ body: string }>`SELECT body FROM kin_messages + WHERE org_id = ${orgId} AND kind = 'system' ORDER BY message_id`; + assert.equal(message?.body, posted?.state.text); + + yield* TestClock.adjust("1 minute"); + assert.equal(yield* service.syncItem(deferral()), "unchanged"); + yield* sql`UPDATE kin_triggers SET next_run_at = NULL WHERE org_id = ${orgId} AND trigger_id = 'deferral:def-1:due'`; + assert.equal(yield* service.syncItem(deferral()), "unchanged"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ nextRunAt, updatedAt }) => [nextRunAt, updatedAt]), + [ + [null, now], + [dueAt - 30 * 60_000, now], + ], + ); + assert.equal((yield* card(orgId))[0]?.revision, 1); + + const moved = "2026-11-16T09:00+05:30"; + assert.equal(yield* service.syncItem(deferral({ due: moved })), "armed"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ nextRunAt }) => nextRunAt), + [Date.parse(moved), Date.parse(moved) - 30 * 60_000], + ); + assert.equal(yield* service.syncItem(deferral({ due: moved, on_due: "remind" })), "armed"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled, nextRunAt }) => [enabled, nextRunAt]), + [ + [1, Date.parse(moved)], + [0, null], + ], + ); + const [updated] = yield* card(orgId); + assert.equal(updated?.revision, 3); + assert.equal(updated?.state.text, "Deferred to Mon 16 Nov, 9:00. I'll remind you then."); + const [run] = yield* sql<{ state: string; dueAt: number; onDue: string }>` + SELECT state, due_at AS "dueAt", on_due AS "onDue" FROM kin_deferral_runs + WHERE org_id = ${orgId} ORDER BY item_id`; + assert.deepEqual(run, { state: "armed", dueAt: Date.parse(moved), onDue: "remind" }); + + // Same fires, different on_due: only the run row and card can tell them apart. + assert.equal(yield* service.syncItem(deferral({ due: moved, on_due: "ask" })), "armed"); + const [asked] = yield* sql<{ onDue: string }>`SELECT on_due AS "onDue" FROM kin_deferral_runs + WHERE org_id = ${orgId} ORDER BY item_id`; + assert.equal(asked?.onDue, "ask"); + assert.equal((yield* card(orgId))[0]?.state.onDue, "ask"); + + yield* sql`UPDATE kin_triggers SET schedule_json = 'not json' + WHERE org_id = ${orgId} AND trigger_id = 'deferral:def-1:due'`; + assert.equal(yield* service.syncItem(deferral({ due: moved, on_due: "ask" })), "armed"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled, nextRunAt }) => [enabled, nextRunAt]), + [ + [1, Date.parse(moved)], + [0, null], + ], + ); + }).pipe(Effect.provide(layer)), +); + +it.effect.each([ + ["done", { status: "done" }], + ["cancelled", { status: "cancelled" }], + ["invalid_at", { invalid_at: "2026-11-09T09:00:00.000Z" }], + ["pre-1970", { due: "1969-12-31" }], + ["year-0", { due: "0000-01-01" }], + ["missing", undefined], +] as const)("disarms on %s and re-arms when reopened", ([, overrides]) => + Effect.gen(function* () { + const { sql, service } = yield* setup(); + yield* service.syncItem(deferral()); + if (overrides === undefined) yield* service.syncOrg(orgId, []); + else assert.equal(yield* service.syncItem(deferral(overrides)), "disarmed"); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled, nextRunAt }) => [enabled, nextRunAt]), + [ + [0, null], + [0, null], + ], + ); + assert.isNotNull((yield* card(orgId))[0]?.closedAt); + const [run] = yield* sql<{ state: string }>`SELECT state FROM kin_deferral_runs + WHERE org_id = ${orgId} ORDER BY item_id`; + assert.equal(run?.state, "disarmed"); + assert.equal( + yield* service.syncItem( + overrides === undefined ? deferral({ status: "done" }) : deferral(overrides), + ), + "unchanged", + ); + + yield* service.syncOrg(orgId, [deferral()]); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled }) => enabled), + [1, 1], + ); + const [reopened] = yield* card(orgId); + assert.isNull(reopened?.closedAt); + assert.lengthOf(yield* card(orgId), 1); + }).pipe(Effect.provide(layer)), +); + +it.effect("keeps organizations apart", () => + Effect.gen(function* () { + const { sql, service } = yield* setup(); + yield* service.syncItem(deferral()); + yield* service.syncItem(deferral({ orgId: otherOrg })); + yield* service.syncOrg(orgId, [deferral({ orgId: otherOrg, status: "done" })]); + assert.deepEqual( + (yield* triggers(orgId)).map(({ enabled }) => enabled), + [0, 0], + ); + assert.deepEqual( + (yield* triggers(otherOrg)).map(({ enabled }) => enabled), + [1, 1], + ); + assert.equal((yield* card(otherOrg))[0]?.closedAt, null); + + const foreign = item("def-foreign", { + kind: "deferral", + path: "deferrals/def-foreign.md", + due, + chat: KinChatId.make(`chat-${otherOrg}`), + }); + assert.equal(yield* service.syncItem(foreign), "armed"); + assert.lengthOf( + yield* sql`SELECT widget_id FROM kin_widgets WHERE org_id = ${orgId} AND state_json LIKE '%def-foreign%' ORDER BY widget_id`, + 0, + ); + const unknown = yield* service + .syncItem(deferral({ orgId: KinOrgId.make("z") })) + .pipe(Effect.flip); + assert.equal(unknown._tag, "KinTriggerSyncError"); + }).pipe(Effect.provide(layer)), +); + +it.effect("syncs each head once, retries failures, and isolates failing items", () => + Effect.gen(function* () { + const { sql } = yield* setup(); + const hooks = yield* Memory.MemorySyncHooks; + const other = deferral({ id: KinMemoryItemId.make("def-2"), path: "deferrals/def-2.md" }); + const snapshot = ( + head: string, + items: ReadonlyArray, + duplicateIds: ReadonlyArray = [], + ) => ({ + head, + items: items.map((head) => ({ head, body: "" })), + duplicateIds: new Set(duplicateIds), + }); + const runs = () => + sql<{ itemId: string; state: string }>`SELECT item_id AS "itemId", state + FROM kin_deferral_runs WHERE org_id = ${orgId} ORDER BY item_id`; + yield* sql`CREATE TRIGGER fail_def_1 BEFORE INSERT ON kin_deferral_runs + WHEN NEW.item_id = 'def-1' BEGIN SELECT RAISE(ABORT, 'fixture'); END`; + yield* hooks.syncItems(orgId, snapshot("h1", [deferral(), other])); + assert.deepEqual(yield* runs(), [{ itemId: "def-2", state: "armed" }]); + + yield* sql`DROP TRIGGER fail_def_1`; + yield* hooks.syncItems(orgId, snapshot("h1", [deferral(), other])); + assert.deepEqual(yield* runs(), [ + { itemId: "def-1", state: "armed" }, + { itemId: "def-2", state: "armed" }, + ]); + yield* sql`UPDATE kin_deferral_runs SET state = 'disarmed' WHERE org_id = ${orgId} AND item_id = 'def-2'`; + yield* hooks.syncItems(orgId, snapshot("h1", [deferral(), other])); + assert.equal((yield* runs())[1]?.state, "disarmed"); + + const copy = deferral({ path: "deferrals/def-1-copy.md" }); + yield* hooks.syncItems(orgId, snapshot("h2", [deferral(), copy, other], ["def-1"])); + assert.deepEqual(yield* runs(), [ + { itemId: "def-1", state: "disarmed" }, + { itemId: "def-2", state: "armed" }, + ]); + assert.deepEqual( + (yield* triggers(orgId)).map(({ id, enabled }) => [id, enabled]), + [ + ["deferral:def-1:due", 0], + ["deferral:def-1:heads_up", 0], + ["deferral:def-2:due", 1], + ["deferral:def-2:heads_up", 1], + ], + ); + + const stuck = deferral({ id: KinMemoryItemId.make("def-3"), path: "deferrals/def-3.md" }); + yield* sql`CREATE TRIGGER fail_def_3 BEFORE INSERT ON kin_deferral_runs + WHEN NEW.item_id = 'def-3' BEGIN SELECT RAISE(ABORT, 'fixture'); END`; + for (let attempt = 0; attempt < 3; attempt++) + yield* hooks.syncItems(orgId, snapshot("h3", [stuck, other])); + yield* sql`DROP TRIGGER fail_def_3`; + yield* hooks.syncItems(orgId, snapshot("h3", [stuck, other])); + assert.notInclude( + (yield* runs()).map(({ itemId }) => itemId), + "def-3", + "a head that failed three times is not retried", + ); + yield* hooks.syncItems(orgId, snapshot("h4", [stuck, other])); + assert.include( + (yield* runs()).map(({ itemId }) => itemId), + "def-3", + ); + }).pipe(Effect.provide(layer)), +); + +it.effect("refuses deferral cards from the model and taps until the dispatcher lands", () => + Effect.gen(function* () { + const { service } = yield* setup(); + yield* service.syncItem(deferral()); + const chat = yield* Chat.KinChatService; + const [posted] = yield* card(orgId); + const upsert = yield* chat + .upsertWidget( + { _tag: "person", orgId, personId: KinPersonId.make(`owner-${orgId}`) }, + { chatId: KinChatId.make(`chat-${orgId}`), type: "deferral", state: posted!.state }, + ) + .pipe(Effect.flip); + assert.equal(upsert._tag === "KinChatError" && upsert.reason, "not_allowed"); + const failure = yield* chat + .act( + { _tag: "person", orgId, personId: KinPersonId.make(`owner-${orgId}`) }, + { + widgetId: KinWidgetId.make(`deferral:${orgId}:def-1`), + revision: 1, + actionId: "remind", + value: KinMemoryItemId.make("def-1"), + clientActionId: "remind", + }, + ) + .pipe(Effect.flip); + assert.equal(failure._tag === "KinChatError" && failure.reason, "not_allowed"); + }).pipe(Effect.provide(layer)), +); diff --git a/apps/server/src/kin/triggers/KinTriggerService.ts b/apps/server/src/kin/triggers/KinTriggerService.ts new file mode 100644 index 0000000000000..0a2c2949591ca --- /dev/null +++ b/apps/server/src/kin/triggers/KinTriggerService.ts @@ -0,0 +1,402 @@ +import { + KinChatId, + type KinDeferralCard, + KinMemoryItemId, + KinMessageId, + KinOrgId, + KinTriggerSchedule, + KinTriggerSubject, + KinWidgetId, + type MemoryItemHead, +} from "@t3tools/contracts"; +import * as Clock from "effect/Clock"; +import * as Context from "effect/Context"; +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 SqlClient from "effect/sql/SqlClient"; +import { isSqlError } from "effect/sql/SqlError"; + +import { toPersistenceSqlError } from "../../persistence/Errors.ts"; +import { KinChatHub } from "../chat/KinChatHub.ts"; +import * as Repository from "../chat/KinChatRepository.ts"; +import * as Memory from "../memory/Memory.ts"; +import * as MemoryCache from "../memory/MemoryCache.ts"; +import { + confirmText, + DeferralSnapshot, + deferralSnapshot, + deferralTriggerId, + deferralWidgetId, + planDeferral, + type DeferralPhase, + type DeferralPlan, +} from "./deferrals.ts"; + +export class KinTriggerSyncError extends Schema.TaggedError()( + "KinTriggerSyncError", + { orgId: KinOrgId, cause: Schema.Defect() }, +) {} + +type SyncItem = MemoryItemHead & { readonly duplicate?: boolean }; +export type SyncResult = "armed" | "disarmed" | "unchanged"; + +export class KinTriggerService extends Context.Service< + KinTriggerService, + { + /** Upserts or disarms one deferral's triggers from its front matter. Idempotent. */ + readonly syncItem: (item: SyncItem) => Effect.Effect; + /** Syncs a whole snapshot; armed deferrals missing from it are disarmed. */ + readonly syncOrg: ( + orgId: KinOrgId, + items: ReadonlyArray, + ) => Effect.Effect; + } +>()("t3/kin/triggers/KinTriggerService") {} + +const phases: ReadonlyArray = ["heads_up", "due"]; +const disarmedPlan: DeferralPlan = { armed: false, dueAt: null, onDue: "remind", phases: [] }; +const encodeSchedule = Schema.encodeEffect(Schema.fromJsonString(KinTriggerSchedule)); +const decodeSchedule = Schema.decodeUnknownEffect(Schema.fromJsonString(KinTriggerSchedule)); +const encodeSubject = Schema.encodeEffect(Schema.fromJsonString(KinTriggerSubject)); +const encodeSnapshot = Schema.encodeEffect(Schema.fromJsonString(DeferralSnapshot)); +const iso = (ms: number) => DateTime.formatIso(DateTime.makeUnsafe(ms)); + +interface StoredTrigger { + readonly runAt: number | undefined; + readonly enabled: boolean; + readonly nextRunAt: number | null; +} +interface Stored { + readonly run: { readonly state: string; readonly dueAt: number | null; readonly onDue: string }; + readonly triggers: Map; +} + +// A fired `once` keeps its runAt with next_run_at cleared; re-syncing must not refire it. +const triggerCurrent = (runAt: number | undefined, row: StoredTrigger | undefined) => + runAt === undefined + ? row === undefined || (!row.enabled && row.nextRunAt === null) + : row?.enabled === true && row.runAt === runAt; + +const isCurrent = (plan: DeferralPlan, stored: Stored | undefined) => + phases.every((phase) => + triggerCurrent( + plan.phases.find((entry) => entry.phase === phase)?.runAt, + stored?.triggers.get(phase), + ), + ) && + (plan.armed + ? stored !== undefined && + stored.run.state !== "disarmed" && + stored.run.dueAt === plan.dueAt && + stored.run.onDue === plan.onDue + : stored === undefined || stored.run.state === "disarmed"); + +const make = Effect.gen(function* () { + const sql = yield* SqlClient.SqlClient; + const cache = yield* MemoryCache.MemoryCache; + const repo = yield* Repository.KinChatRepository; + const hub = yield* Effect.serviceOption(KinChatHub); + const publish = (event: Parameters[0]) => + Option.isSome(hub) ? sql.afterCommit(hub.value.publish(event)) : Effect.void; + + // Trigger rows are only written in the same transaction as their run row. + const readStored = Effect.fn("KinTriggerService.readStored")(function* ( + orgId: KinOrgId, + itemId?: KinMemoryItemId, + ) { + const rows = yield* sql<{ + itemId: string; + state: string; + dueAt: number | null; + onDue: string; + triggerId: string | null; + schedule: string | null; + enabled: number | null; + nextRunAt: number | null; + }>` + SELECT r.item_id AS "itemId", r.state, r.due_at AS "dueAt", r.on_due AS "onDue", + t.trigger_id AS "triggerId", t.schedule_json AS schedule, + t.enabled, t.next_run_at AS "nextRunAt" + FROM kin_deferral_runs r + LEFT JOIN kin_triggers t ON t.org_id = r.org_id + AND t.trigger_id IN ('deferral:' || r.item_id || ':heads_up', 'deferral:' || r.item_id || ':due') + WHERE r.org_id = ${orgId} ${itemId === undefined ? sql`` : sql`AND r.item_id = ${itemId}`} + ORDER BY r.item_id, t.trigger_id + `; + const stored = new Map(); + for (const row of rows) { + let entry = stored.get(row.itemId); + if (entry === undefined) { + entry = { + run: { state: row.state, dueAt: row.dueAt, onDue: row.onDue }, + triggers: new Map(), + }; + stored.set(row.itemId, entry); + } + const phase = phases.find((each) => deferralTriggerId(row.itemId, each) === row.triggerId); + if (phase === undefined || row.schedule === null) continue; + // An undecodable row reads as stale, so the next apply overwrites it instead of failing the org. + const schedule = yield* decodeSchedule(row.schedule).pipe(Effect.option); + entry.triggers.set(phase, { + runAt: + Option.isSome(schedule) && schedule.value.type === "once" + ? Date.parse(schedule.value.runAt) + : Number.NaN, + enabled: row.enabled === 1, + nextRunAt: row.nextRunAt, + }); + } + return stored; + }); + + const writeTrigger = Effect.fn("KinTriggerService.writeTrigger")(function* ( + orgId: KinOrgId, + itemId: KinMemoryItemId, + phase: DeferralPhase, + runAt: number | undefined, + timeZone: string, + now: number, + ) { + const id = deferralTriggerId(itemId, phase); + if (runAt === undefined) + return yield* sql`UPDATE kin_triggers SET enabled = 0, next_run_at = NULL, + updated_at = max(updated_at, ${now}) WHERE org_id = ${orgId} AND trigger_id = ${id}`; + const schedule = yield* encodeSchedule({ type: "once", runAt: iso(runAt) }); + const subject = yield* encodeSubject({ type: "deferral", itemId, phase }); + const inserted = yield* sql` + INSERT INTO kin_triggers (trigger_id, org_id, subject_json, schedule_json, time_zone, enabled, + next_run_at, last_fire_id, created_at, updated_at) + VALUES (${id}, ${orgId}, ${subject}, ${schedule}, ${timeZone}, 1, ${runAt}, NULL, ${now}, ${now}) + ON CONFLICT DO NOTHING RETURNING trigger_id + `; + if (inserted.length === 0) + yield* sql`UPDATE kin_triggers SET subject_json = ${subject}, schedule_json = ${schedule}, + time_zone = ${timeZone}, enabled = 1, next_run_at = ${runAt}, + updated_at = max(updated_at, ${now}) + WHERE org_id = ${orgId} AND trigger_id = ${id}`; + }); + + const syncCard = Effect.fn("KinTriggerService.syncCard")(function* ( + orgId: KinOrgId, + itemId: KinMemoryItemId, + item: SyncItem | undefined, + plan: DeferralPlan, + timeZone: string, + now: number, + ) { + const widgetId = KinWidgetId.make(deferralWidgetId(orgId, itemId)); + const existing = yield* repo.getWidget({ orgId, widgetId }); + const at = iso(now); + if (!plan.armed || plan.dueAt === null || item === undefined) { + if (Option.isNone(existing) || existing.value.closedAt !== null) return; + const widget = yield* repo.updateWidget({ + ...existing.value, + expectedRevision: existing.value.revision, + closedAt: at, + updatedAt: at, + }); + return yield* publish({ type: "widget.updated", orgId, widget }); + } + const state: KinDeferralCard = { + itemId, + title: item.title, + dueAt: iso(plan.dueAt), + onDue: plan.onDue, + text: confirmText(plan.dueAt, plan.onDue, timeZone), + }; + if (Option.isSome(existing)) { + const widget = yield* repo.updateWidget({ + ...existing.value, + expectedRevision: existing.value.revision, + state, + closedAt: null, + updatedAt: at, + }); + return yield* publish({ type: "widget.updated", orgId, widget }); + } + // Only kin_defer items name a chat; other deferrals arm without a card. + if (item.chat === undefined) return; + const chatId = KinChatId.make(item.chat); + const [chat] = yield* sql`SELECT 1 FROM kin_chats + WHERE org_id = ${orgId} AND chat_id = ${chatId} ORDER BY chat_id`; + if (chat === undefined) + return yield* Effect.logWarning("Deferral chat is not in its organization", { + orgId, + itemId, + }); + const message = yield* repo.insertMessage({ + orgId, + chatId, + messageId: KinMessageId.make(widgetId), + author: { _tag: "system" }, + kind: "system", + body: state.text, + intent: null, + mentions: [], + replyTo: null, + widgetId: null, + floorRunId: null, + status: "posted", + sentBy: null, + clientMessageId: null, + createdAt: at, + editedAt: null, + }); + const widget = { + orgId, + chatId, + messageId: message.messageId, + widgetId, + widgetClass: "native" as const, + type: "deferral", + state, + source: null, + feed: null, + awaiting: [], + pinnedAt: null, + closedAt: null, + updatedAt: at, + }; + yield* repo.insertWidget(widget); + yield* publish({ type: "message.posted", orgId, message }); + yield* publish({ type: "widget.updated", orgId, widget: { ...widget, revision: 1 } }); + }); + + const apply = Effect.fn("KinTriggerService.apply")(function* ( + orgId: KinOrgId, + itemId: KinMemoryItemId, + item: SyncItem | undefined, + plan: DeferralPlan, + timeZone: string, + now: number, + ) { + return yield* sql.withTransaction( + Effect.gen(function* () { + const [org] = yield* sql`SELECT 1 FROM kin_orgs WHERE org_id = ${orgId} ORDER BY org_id`; + if (org === undefined) return yield* Effect.fail("unknown_org" as const); + const stored = (yield* readStored(orgId, itemId)).get(itemId); + if (isCurrent(plan, stored)) return "unchanged" as const; + for (const phase of phases) { + const runAt = plan.phases.find((entry) => entry.phase === phase)?.runAt; + if (!triggerCurrent(runAt, stored?.triggers.get(phase))) + yield* writeTrigger(orgId, itemId, phase, runAt, timeZone, now); + } + if (plan.armed && item !== undefined) { + const snapshot = yield* encodeSnapshot(deferralSnapshot(item)); + const inserted = yield* sql` + INSERT INTO kin_deferral_runs (org_id, item_id, state, due_at, on_due, snapshot_json, updated_at) + VALUES (${orgId}, ${itemId}, 'armed', ${plan.dueAt}, ${plan.onDue}, ${snapshot}, ${now}) + ON CONFLICT DO NOTHING RETURNING item_id + `; + if (inserted.length === 0) + yield* sql`UPDATE kin_deferral_runs SET state = 'armed', due_at = ${plan.dueAt}, + on_due = ${plan.onDue}, snapshot_json = ${snapshot}, updated_at = ${now} + WHERE org_id = ${orgId} AND item_id = ${itemId}`; + } else + yield* sql`UPDATE kin_deferral_runs SET state = 'disarmed', updated_at = ${now} + WHERE org_id = ${orgId} AND item_id = ${itemId} AND state <> 'disarmed'`; + yield* syncCard(orgId, itemId, item, plan, timeZone, now); + return plan.armed ? ("armed" as const) : ("disarmed" as const); + }), + ); + }); + + const wrap = (orgId: KinOrgId) => + Effect.mapError( + (cause: unknown) => + new KinTriggerSyncError({ + orgId, + cause: isSqlError(cause) ? toPersistenceSqlError("KinTriggerService.sync")(cause) : cause, + }), + ); + + return KinTriggerService.of({ + syncItem: Effect.fn("KinTriggerService.syncItem")(function* (item) { + if (item.kind !== "deferral") return "unchanged" as const; + const timeZone = yield* cache.ownerTimeZone(item.orgId); + const now = yield* Clock.currentTimeMillis; + return yield* apply(item.orgId, item.id, item, planDeferral(item), timeZone, now).pipe( + wrap(item.orgId), + ); + }), + syncOrg: Effect.fn("KinTriggerService.syncOrg")(function* (orgId, items) { + const stored = yield* readStored(orgId).pipe(wrap(orgId)); + const present = new Set(); + const pending: Array = []; + for (const item of items) { + if (item.orgId !== orgId || item.kind !== "deferral") continue; + present.add(item.id); + const plan = planDeferral(item); + if (!isCurrent(plan, stored.get(item.id))) pending.push([item.id, item, plan]); + } + for (const [itemId, entry] of stored) + if (!present.has(itemId) && entry.run.state !== "disarmed") + pending.push([KinMemoryItemId.make(itemId), undefined, disarmedPlan]); + if (pending.length === 0) return; + const timeZone = yield* cache.ownerTimeZone(orgId); + const now = yield* Clock.currentTimeMillis; + const failures: Array = []; + for (const [itemId, item, plan] of pending) + yield* apply(orgId, itemId, item, plan, timeZone, now).pipe( + wrap(orgId), + Effect.catch((error) => { + failures.push(error); + return Effect.logWarning("Could not sync deferral", { orgId, itemId, cause: error }); + }), + ); + if (failures.length > 0) return yield* failures[0]!; + }), + }); +}); + +export const layer = Layer.effect(KinTriggerService, make).pipe(Layer.provide(MemoryCache.layer)); + +const maxSyncAttempts = 3; + +/** Arms deferrals from each new memory head; a failed sync retries on the next few loads. */ +export const syncHooksLayer = Layer.effect( + Memory.MemorySyncHooks, + Effect.gen(function* () { + const service = yield* KinTriggerService; + const syncedHeads = new Map(); + const failedAttempts = new Map(); + return { + syncItems: Effect.fn("KinTriggerService.syncItems")(function* (orgId, snapshot) { + if (syncedHeads.get(orgId) === snapshot.head) return; + const failed = failedAttempts.get(orgId); + const attempt = failed?.head === snapshot.head ? failed.count + 1 : 1; + yield* service + .syncOrg( + orgId, + snapshot.items.map(({ head }) => ({ + ...head, + duplicate: snapshot.duplicateIds.has(head.id), + })), + ) + .pipe( + Effect.tap(() => + Effect.sync(() => { + syncedHeads.set(orgId, snapshot.head); + failedAttempts.delete(orgId); + }), + ), + Effect.catch((error) => { + // A permanent failure would otherwise rerun the sync inside the memory lock on every load. + const giveUp = attempt >= maxSyncAttempts; + if (giveUp) syncedHeads.set(orgId, snapshot.head); + else failedAttempts.set(orgId, { head: snapshot.head, count: attempt }); + return Effect.logWarning( + giveUp + ? "Could not sync deferral triggers; skipping this head" + : "Could not sync deferral triggers; retrying on next load", + { orgId, attempt, cause: error }, + ); + }), + ); + }), + }; + }), +); diff --git a/apps/server/src/kin/triggers/deferrals.test.ts b/apps/server/src/kin/triggers/deferrals.test.ts new file mode 100644 index 0000000000000..706d45c58f43c --- /dev/null +++ b/apps/server/src/kin/triggers/deferrals.test.ts @@ -0,0 +1,172 @@ +import { assert, it } from "@effect/vitest"; +import { + KinAgentId, + KinChatId, + KinEvent, + KinEventId, + KinMemberId, + KinMessageId, + KinPersonId, + KinWakeupId, + KinWidgetId, +} from "@t3tools/contracts"; +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 SqlClient from "effect/sql/SqlClient"; +import * as TestClock from "effect/testing/TestClock"; + +import * as Repository from "../chat/KinChatRepository.ts"; +import * as Queue from "../lead/KinEventQueue.ts"; +import * as MemoryWriter from "../memory/MemoryWriter.ts"; +import * as Deferrals from "./deferrals.ts"; +import * as TriggerService from "./KinTriggerService.ts"; +import { fixture, item, orgId, otherOrg, seed } from "./routines.testkit.ts"; + +const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown)); +const decodeEvent = Schema.decodeSync(KinEvent); +const deferral = item("def-1", { + kind: "deferral", + path: "deferrals/def-1.md", + due: "2026-11-13T09:00+05:30", + on_due: "start", + chat: KinChatId.make("chat-a"), +}); +const widgetId = KinWidgetId.make(`deferral:${orgId}:def-1`); + +it.effect("applies verified owner taps on the confirm card and ignores forged ones", () => + Effect.gen(function* () { + yield* seed(); + yield* TestClock.setTime(Date.parse("2026-11-09T09:00:00.000Z")); + const sql = yield* SqlClient.SqlClient; + const repo = yield* Repository.KinChatRepository; + const queue = yield* Queue.KinEventQueue; + const deferrals = yield* Deferrals.Deferrals; + yield* (yield* TriggerService.KinTriggerService).syncItem(deferral); + const staged: MemoryWriter.MemoryChange[] = []; + const writer = Layer.mock(MemoryWriter.MemoryWriter)({ + stage: (_org, _wakeup, change) => Effect.sync(() => void staged.push(change)), + }); + const tapOnce = Effect.fn("test.deferralTap")(function* ( + actionId: string, + label: string, + target: KinWidgetId = widgetId, + ) { + const memberId = "owner-member-a"; + // Stands in for the gated dispatcher: chat act refuses deferral taps today. + const message = yield* repo.insertMessage({ + orgId, + chatId: KinChatId.make("chat-a"), + messageId: KinMessageId.make(`tap-${actionId}-${label}`), + author: { + _tag: "human", + personId: KinPersonId.make("owner-a"), + memberId: KinMemberId.make(memberId), + }, + kind: "widget_action", + body: encodeJson({ widgetId: target, revision: 1, actionId, value: "def-1" }), + intent: null, + mentions: [], + replyTo: KinMessageId.make(target), + widgetId: target, + floorRunId: null, + status: "posted", + sentBy: KinPersonId.make("owner-a"), + clientMessageId: { kind: "act", id: `${actionId}-${label}` }, + createdAt: "2026-11-09T09:00:00.000Z", + editedAt: null, + }); + const eventId = `${actionId}-${label}`; + yield* queue.enqueue( + decodeEvent({ + _tag: "widget.action", + orgId, + eventId, + agentId: "lead-a", + receivedAt: "2026-11-09T09:00:00.000Z", + dedupeKey: eventId, + provenance: { _tag: "human", personId: "owner-a", memberId }, + chatId: "chat-a", + messageId: message.messageId, + actionId, + }), + ); + yield* TestClock.adjust("20 seconds"); + const wakeupId = KinWakeupId.make(`wake-${eventId}`); + yield* queue.claim({ orgId, agentId: KinAgentId.make("lead-a"), wakeupId, model: "fixture" }); + if (label === "demoted") + yield* sql`UPDATE kin_chat_members SET role = 'member' WHERE org_id = ${orgId} AND member_id = ${memberId}`; + const result = yield* deferrals + .act(orgId, wakeupId, KinEventId.make(eventId)) + .pipe(Effect.provide(writer), Effect.result); + const forged = yield* deferrals + .act(otherOrg, wakeupId, KinEventId.make(eventId)) + .pipe(Effect.provide(writer), Effect.flip); + assert.equal(forged._tag, "DeferralError"); + yield* queue.finish({ orgId, wakeupId, status: "completed" }); + return result; + }); + const tap = (actionId: string, label: string, target?: KinWidgetId) => + Effect.scoped(tapOnce(actionId, label, target)); + + const remind = yield* tap("remind", "owner"); + assert.equal(remind._tag === "Success" && remind.success.action, "remind"); + assert.lengthOf(staged, 1); + assert.equal(staged[0]?.sourceEventId, "remind-owner"); + assert.include(staged[0]!.content, "on_due: remind"); + + const change = yield* tap("change", "owner"); + assert.equal(change._tag === "Success" && change.success.action, "change"); + assert.lengthOf(staged, 1); + + const real = Option.getOrThrow(yield* repo.getWidget({ orgId, widgetId })); + const forgedId = KinWidgetId.make("model-card"); + const anchor = yield* repo.insertMessage({ + orgId, + chatId: real.chatId, + messageId: KinMessageId.make(forgedId), + author: { _tag: "system" }, + kind: "system", + body: "", + intent: null, + mentions: [], + replyTo: null, + widgetId: null, + floorRunId: null, + status: "posted", + sentBy: null, + clientMessageId: null, + createdAt: "2026-11-09T09:00:00.000Z", + editedAt: null, + }); + yield* repo.insertWidget({ + orgId, + chatId: real.chatId, + messageId: anchor.messageId, + widgetId: forgedId, + widgetClass: "native", + type: "deferral", + state: real.state, + source: null, + feed: null, + awaiting: [], + pinnedAt: null, + closedAt: null, + updatedAt: "2026-11-09T09:00:00.000Z", + }); + assert.equal((yield* tap("remind", "forged", forgedId))._tag, "Failure"); + assert.lengthOf(staged, 1); + + const member = yield* tap("remind", "demoted"); + assert.equal(member._tag, "Failure"); + assert.lengthOf(staged, 1); + }).pipe( + Effect.provide( + Deferrals.layer.pipe( + Layer.provideMerge(TriggerService.layer), + Layer.provideMerge(fixture([deferral])), + ), + ), + ), +); diff --git a/apps/server/src/kin/triggers/deferrals.ts b/apps/server/src/kin/triggers/deferrals.ts new file mode 100644 index 0000000000000..a90798dab3ef9 --- /dev/null +++ b/apps/server/src/kin/triggers/deferrals.ts @@ -0,0 +1,166 @@ +import { + KinChatId, + KinDeferralCard, + KinEventId, + KinMemoryItemId, + KinOrgId, + KinTriggerId, + type MemoryItemHead, +} from "@t3tools/contracts"; +import * as Context from "effect/Context"; +import * as Effect from "effect/Effect"; +import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; +import * as SqlClient from "effect/sql/SqlClient"; +import { stringify } from "yaml"; + +import * as Repository from "../chat/KinChatRepository.ts"; +import * as Memory from "../memory/Memory.ts"; +import * as MemoryWriter from "../memory/MemoryWriter.ts"; +import { memoryDateMillis } from "../memory/frontMatter.ts"; +import { deferralCardActions } from "../widgets/deferralCard.ts"; +import { verifyOwnerTap } from "./ownerCheck.ts"; + +const HEADS_UP_MS = 30 * 60_000; +export type OnDue = KinDeferralCard["onDue"]; +export type DeferralPhase = "heads_up" | "due"; + +export interface DeferralPlan { + readonly armed: boolean; + readonly dueAt: number | null; + readonly onDue: OnDue; + readonly phases: ReadonlyArray<{ readonly phase: DeferralPhase; readonly runAt: number }>; +} + +export const deferralTriggerId = (itemId: string, phase: DeferralPhase) => + KinTriggerId.make(`deferral:${itemId}:${phase}`); +export const deferralWidgetId = (orgId: string, itemId: string) => `deferral:${orgId}:${itemId}`; + +// A deferral without on_due only reminds: silence never starts work. Pre-epoch run +// times would fail every scheduler tick, so they leave the item unarmed. +export function planDeferral( + item: MemoryItemHead & { readonly duplicate?: boolean }, +): DeferralPlan { + const onDue = item.on_due ?? "remind"; + const due = memoryDateMillis(item.due); + const dueAt = Number.isFinite(due) ? due : null; + const armed = + item.kind === "deferral" && + item.status === "open" && + item.invalid_at === null && + item.superseded_by === null && + item.duplicate !== true && + dueAt !== null; + if (!armed || dueAt === null) return { armed: false, dueAt, onDue, phases: [] }; + const dueFire = { phase: "due" as const, runAt: dueAt }; + const phases: DeferralPlan["phases"] = + onDue === "start" ? [{ phase: "heads_up", runAt: dueAt - HEADS_UP_MS }, dueFire] : [dueFire]; + if (phases.some(({ runAt }) => runAt < 0)) return { armed: false, dueAt, onDue, phases: [] }; + return { armed, dueAt, onDue, phases }; +} + +/** The item half of the recheck baseline; TRIG-8 adds the GitHub half. */ +export const DeferralSnapshot = Schema.Struct({ + recordedAt: Schema.String, + supersededBy: Schema.NullOr(KinMemoryItemId), + links: Schema.Array(Schema.String), +}); +export const deferralSnapshot = (item: MemoryItemHead): typeof DeferralSnapshot.Type => ({ + recordedAt: item.recorded_at, + supersededBy: item.superseded_by, + links: item.links, +}); + +const then: Record = { + start: "I'll start then.", + remind: "I'll remind you then.", + ask: "I'll ask you then.", + chase: "I'll chase it then.", +}; + +export function confirmText(dueAt: number, onDue: OnDue, timeZone: string): string { + const parts = Object.fromEntries( + new Intl.DateTimeFormat("en-GB", { + timeZone, + weekday: "short", + day: "numeric", + month: "short", + hour: "numeric", + minute: "2-digit", + hourCycle: "h23", + }) + .formatToParts(dueAt) + .map((part) => [part.type, part.value]), + ); + return `Deferred to ${parts.weekday} ${parts.day} ${parts.month}, ${Number(parts.hour)}:${parts.minute}. ${then[onDue]}`; +} + +export class DeferralError extends Schema.TaggedError()("DeferralError", { + orgId: KinOrgId, + cause: Schema.Defect(), +}) {} + +const decodeCard = Schema.decodeUnknownEffect(KinDeferralCard); +const decodeAction = Schema.decodeUnknownEffect( + Schema.Struct({ actionId: Schema.Literals(deferralCardActions), value: KinMemoryItemId }), +); + +export class Deferrals extends Context.Service< + Deferrals, + { + /** Applies a verified owner tap on a deferral card. [Change] hands the item to the lead. */ + readonly act: ( + orgId: KinOrgId, + wakeupId: string, + eventId: KinEventId, + ) => Effect.Effect< + { + readonly chatId: KinChatId; + readonly itemId: KinMemoryItemId; + readonly action: (typeof deferralCardActions)[number]; + }, + DeferralError, + MemoryWriter.MemoryWriter + >; + } +>()("t3/kin/triggers/deferrals") {} + +const make = Effect.gen(function* () { + const memory = yield* Memory.Memory; + const sql = yield* SqlClient.SqlClient; + const repo = yield* Repository.KinChatRepository; + return Deferrals.of({ + act: Effect.fn("Deferrals.act")((orgId, wakeupId, eventId) => + Effect.gen(function* () { + const writer = yield* MemoryWriter.MemoryWriter; + const tap = yield* verifyOwnerTap(orgId, wakeupId, eventId, "deferral").pipe( + Effect.provideService(SqlClient.SqlClient, sql), + Effect.provideService(Repository.KinChatRepository, repo), + ); + const action = yield* decodeAction(tap.action); + const card = yield* decodeCard(tap.widget.state); + if ( + card.itemId !== action.value || + tap.widget.widgetId !== deferralWidgetId(orgId, card.itemId) + ) + return yield* Effect.fail("unknown_item" as const); + if (action.actionId === "remind") { + const item = yield* memory.readItemQuietly(orgId, card.itemId); + if (item.head.kind !== "deferral" || item.head.status !== "open") + return yield* Effect.fail("not_open" as const); + if (item.head.on_due !== "remind") { + const { orgId: _org, path, ...frontMatter } = item.head; + yield* writer.stage(orgId, wakeupId, { + path, + content: `---\n${stringify({ ...frontMatter, on_due: "remind" })}---\n${item.body}`, + sourceEventId: eventId, + }); + } + } + return { chatId: tap.chatId, itemId: card.itemId, action: action.actionId }; + }).pipe(Effect.mapError((cause) => new DeferralError({ orgId, cause }))), + ), + }); +}); + +export const layer = Layer.effect(Deferrals, make); diff --git a/apps/server/src/kin/triggers/ownerCheck.ts b/apps/server/src/kin/triggers/ownerCheck.ts index f31102d5990c0..d554c4d7d843b 100644 --- a/apps/server/src/kin/triggers/ownerCheck.ts +++ b/apps/server/src/kin/triggers/ownerCheck.ts @@ -37,12 +37,20 @@ type Selection = typeof Selection.Type; const decodeCard = Schema.decodeUnknownEffect(KinOwnerCheckCard); const decodeEvent = Schema.decodeUnknownEffect(Schema.fromJsonString(KinEvent)); const decodeAction = Schema.decodeUnknownEffect( + Schema.Struct({ + widgetId: KinWidgetId, + revision: Schema.Int, + actionId: Schema.Literals(["keep", "update", "drop"]), + value: KinMemoryItemId, + }), +); +const decodeTap = Schema.decodeUnknownEffect( Schema.fromJsonString( Schema.Struct({ widgetId: KinWidgetId, revision: Schema.Int, - actionId: Schema.Literals(["keep", "update", "drop"]), - value: KinMemoryItemId, + actionId: Schema.String, + value: Schema.optional(Schema.Unknown), }), ), ); @@ -95,6 +103,66 @@ export function pickOwnerCheckItems( .map(({ item, rank }) => ({ itemId: item.id, reason: reasons[rank] ?? "no_evidence" })); } +/** Verifies a claimed widget tap as the org owner's own action on an open card of `type`. */ +export const verifyOwnerTap = Effect.fn("OwnerCheck.verifyOwnerTap")(function* ( + orgId: KinOrgId, + wakeupId: string, + eventId: KinEventId, + type: string, +) { + const sql = yield* SqlClient.SqlClient; + const repo = yield* Repository.KinChatRepository; + return yield* sql + .withTransaction( + Effect.gen(function* () { + const [row] = yield* sql<{ + json: string; + }>`SELECT e.json FROM kin_events e JOIN kin_wakeups w ON w.org_id = e.org_id AND w.wakeup_id = e.wakeup_id WHERE e.org_id = ${orgId} AND e.event_id = ${eventId} AND e.wakeup_id = ${wakeupId} AND e.state = 'claimed' AND w.status = 'running' ORDER BY e.event_id`; + if (row === undefined) return yield* Effect.fail("unclaimed_action" as const); + const event = yield* decodeEvent(row.json); + if ( + event.orgId !== orgId || + event.eventId !== eventId || + event._tag !== "widget.action" || + event.provenance._tag !== "human" + ) + return yield* Effect.fail("not_owner" as const); + const message = yield* repo.getMessage({ orgId, messageId: event.messageId }); + if ( + Option.isNone(message) || + message.value.chatId !== event.chatId || + message.value.kind !== "widget_action" || + message.value.authorRole !== "owner" || + message.value.author._tag !== "human" || + message.value.author.personId !== event.provenance.personId || + message.value.author.memberId !== event.provenance.memberId + ) + return yield* Effect.fail("not_owner" as const); + const owners = + yield* sql`SELECT m.member_id FROM kin_chat_members m JOIN kin_agents a ON a.org_id = m.org_id AND a.owner_person_id = m.person_id WHERE m.org_id = ${orgId} AND m.member_id = ${event.provenance.memberId} AND m.chat_id = ${event.chatId} AND m.person_id = ${event.provenance.personId} AND m.role = 'owner' AND m.left_at IS NULL AND a.agent_id = ${event.agentId} AND a.retired_at IS NULL ORDER BY m.member_id`; + if (owners.length === 0) return yield* Effect.fail("not_owner" as const); + const action = yield* decodeTap(message.value.body); + const widget = yield* repo.getWidget({ orgId, widgetId: action.widgetId }); + if ( + Option.isNone(widget) || + widget.value.type !== type || + widget.value.chatId !== event.chatId || + message.value.widgetId !== action.widgetId || + widget.value.closedAt !== null || + widget.value.revision !== action.revision || + event.actionId !== action.actionId + ) + return yield* Effect.fail("invalid_card" as const); + return { action, chatId: event.chatId, widget: widget.value }; + }), + ) + .pipe( + Effect.mapError((cause) => + isSqlError(cause) ? toPersistenceSqlError("OwnerCheck.verifyOwnerTap")(cause) : cause, + ), + ); +}); + export class OwnerCheckError extends Schema.TaggedError()("OwnerCheckError", { orgId: KinOrgId, cause: Schema.Defect(), @@ -233,62 +301,17 @@ const make = Effect.gen(function* () { orgId, Effect.gen(function* () { const writer = yield* MemoryWriter.MemoryWriter; - const verified = yield* sql - .withTransaction( - Effect.gen(function* () { - const [row] = yield* sql<{ - json: string; - }>`SELECT e.json FROM kin_events e JOIN kin_wakeups w ON w.org_id = e.org_id AND w.wakeup_id = e.wakeup_id WHERE e.org_id = ${orgId} AND e.event_id = ${eventId} AND e.wakeup_id = ${wakeupId} AND e.state = 'claimed' AND w.status = 'running' ORDER BY e.event_id`; - if (row === undefined) return yield* Effect.fail("unclaimed_action"); - const event = yield* decodeEvent(row.json); - if ( - event.orgId !== orgId || - event.eventId !== eventId || - event._tag !== "widget.action" || - event.provenance._tag !== "human" - ) - return yield* Effect.fail("not_owner"); - const message = yield* repo.getMessage({ orgId, messageId: event.messageId }); - if ( - Option.isNone(message) || - message.value.chatId !== event.chatId || - message.value.kind !== "widget_action" || - message.value.authorRole !== "owner" || - message.value.author._tag !== "human" || - message.value.author.personId !== event.provenance.personId || - message.value.author.memberId !== event.provenance.memberId - ) - return yield* Effect.fail("not_owner"); - const owners = - yield* sql`SELECT m.member_id FROM kin_chat_members m JOIN kin_agents a ON a.org_id = m.org_id AND a.owner_person_id = m.person_id WHERE m.org_id = ${orgId} AND m.member_id = ${event.provenance.memberId} AND m.chat_id = ${event.chatId} AND m.person_id = ${event.provenance.personId} AND m.role = 'owner' AND m.left_at IS NULL AND a.agent_id = ${event.agentId} AND a.retired_at IS NULL ORDER BY m.member_id`; - if (owners.length === 0) return yield* Effect.fail("not_owner"); - const action = yield* decodeAction(message.value.body); - const widget = yield* repo.getWidget({ orgId, widgetId: action.widgetId }); - if ( - Option.isNone(widget) || - widget.value.type !== "owner_check" || - widget.value.chatId !== event.chatId || - message.value.widgetId !== action.widgetId || - widget.value.closedAt !== null || - widget.value.revision !== action.revision || - event.actionId !== action.actionId - ) - return yield* Effect.fail("invalid_card"); - const card = yield* decodeCard(widget.value.state); - if ( - !card.items.some( - (item) => item.itemId === action.value && item.handled === undefined, - ) - ) - return yield* Effect.fail("unknown_item"); - return { action, chatId: event.chatId, widget: widget.value, card }; - }), - ) - .pipe( - Effect.mapError((cause) => - isSqlError(cause) ? toPersistenceSqlError("OwnerCheck.act")(cause) : cause, - ), - ); + const tap = yield* verifyOwnerTap(orgId, wakeupId, eventId, "owner_check").pipe( + Effect.provideService(SqlClient.SqlClient, sql), + Effect.provideService(Repository.KinChatRepository, repo), + ); + const action = yield* decodeAction(tap.action); + const card = yield* decodeCard(tap.widget.state); + if ( + !card.items.some((item) => item.itemId === action.value && item.handled === undefined) + ) + return yield* Effect.fail("unknown_item"); + const verified = { action, chatId: tap.chatId, widget: tap.widget, card }; const item = yield* memory.readItemQuietly(orgId, verified.action.value); if (verified.action.actionId !== "update") { const { orgId: _org, path, ...frontMatter } = item.head; diff --git a/apps/server/src/kin/widgets/deferralCard.ts b/apps/server/src/kin/widgets/deferralCard.ts new file mode 100644 index 0000000000000..c0e644b6879a4 --- /dev/null +++ b/apps/server/src/kin/widgets/deferralCard.ts @@ -0,0 +1,4 @@ +// Taps need the owner-tap dispatcher that also gates the owner check; see the +// deferral card release gate in docs/kin/specs/triggers.md. +export const deferralCardActionsReady = false; +export const deferralCardActions = ["change", "remind"] as const; diff --git a/apps/server/src/kin/widgets/registry.ts b/apps/server/src/kin/widgets/registry.ts index 31b038ab429bf..e4da474d02201 100644 --- a/apps/server/src/kin/widgets/registry.ts +++ b/apps/server/src/kin/widgets/registry.ts @@ -1,10 +1,16 @@ -import { KinChatError, KinTaskCardState, KinOwnerCheckCard } from "@t3tools/contracts"; +import { + KinChatError, + KinDeferralCard, + KinTaskCardState, + KinOwnerCheckCard, +} from "@t3tools/contracts"; import * as Effect from "effect/Effect"; import * as Schema from "effect/Schema"; const schemas = new Map>([ ["task", KinTaskCardState], ["owner_check", KinOwnerCheckCard], + ["deferral", KinDeferralCard], ]); export const validateState = Effect.fn("KinWidgetRegistry.validateState")(function* ( diff --git a/docs/kin/specs/triggers.md b/docs/kin/specs/triggers.md index 69d876d00f1e1..4ff8bdfa62299 100644 --- a/docs/kin/specs/triggers.md +++ b/docs/kin/specs/triggers.md @@ -113,7 +113,7 @@ Defaults: brief 08:30 daily, summary 18:30 Mon–Fri, dream 03:00 daily, full re | Kind | Late policy (decided by the consumer, using `lateByMs` and owner time) | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Deferral `heads_up` | If `due` has also passed, skip the heads-up and handle `due` as late. | -| Deferral `due` | Run the due flow with "This was due at 9:00"; the grace starts from now. | +| Deferral `due` | Within the 30-minute grace, run the due flow with "This was due at 9:00"; the grace starts from now. Older fires ask, never start. | | Reminder, follow-up | Deliver with "This was due at …". Pings respect quiet hours. | | Morning brief | Post if before the evening summary time; otherwise fold into the evening summary. | | Evening summary | Post if before the next dream; otherwise fold into the next morning brief. | @@ -203,9 +203,20 @@ Arming comes from memory. When the front-matter cache (LEAD) sees a `deferrals/* | `ask` | `due` only | post a decision card | | `chase` | `due` only | ping the promiser (ping rules) | -Item edits move or disarm the triggers: a new `due` re-arms; `status` other than `open` or a set `invalid_at` disables them. A due time already past at save fires at once, marked late; no "pick a future time" error. +Item edits move or disarm the triggers: a new `due` re-arms; `status` other than `open` or a set `invalid_at` disables them. A due time already past at save fires at once, marked late; no "pick a future time" error. A missing `on_due` means `remind`, so silence never starts work. -**Confirm.** When the lead calls `kin_defer` (LEAD), Kin writes the item, arms the triggers, and the lead posts a `KinDeferralCard` widget (CHAT envelope): "Deferred to Fri 13 Nov, 9:00. I'll start then." [Change] [Just remind me]. [Just remind me] sets `on_due: remind`, and the triggers re-arm. +The cache hook is `MemorySyncHooks` in [`Memory.ts`](../../../apps/server/src/kin/memory/Memory.ts): each new head goes once to `KinTriggerService.syncOrg`, which also disarms armed deferrals missing from the snapshot or sharing a duplicate id. A failing item is logged without blocking the others, and the head retries on the next two loads, then waits for the next head. The deferral `trigger_reconcile` described below is not built yet, so until it is, a new head is the only recovery. A due time whose fires would land before 1970 never arms; `kin_defer` accepts only years 2000–2099. A commit to the default branch moves the cache to the new head and reloads it, so a `kin_defer` item arms when its wake-up commits, not at the next wake-up; shadow (L0) commits never arm. Trigger ids are `deferral::heads_up|due`. Re-syncing an unchanged `due` writes nothing, so a fired `once` is never re-armed. The run row in `kin_deferral_runs` (migration K016) holds the snapshot and an `armed`/`disarmed` state; TRIG-8 owns the due-flow states. The snapshot holds the item half only (`recorded_at`, `superseded_by`, links). There is no GitHub reader in Kin yet, so TRIG-8 must add the GitHub half (issue/PR state, assignees, linked PRs) at arm time before the due flow ships. + +**Confirm.** When the lead calls `kin_defer` (LEAD), Kin writes the item, arms the triggers, and the lead posts a `KinDeferralCard` widget (CHAT envelope): "Deferred to Fri 13 Nov, 9:00. I'll start then." [Change] [Just remind me]. [Just remind me] sets `on_due: remind`, and the triggers re-arm. [Change] writes nothing: it hands the item to the lead, which asks the owner what to change, marks the old item `cancelled` and calls `kin_defer` for the new one. + +Code posts the card, never the model. It goes to the item's `chat` when that chat belongs to the item's org; deferrals without a chat arm without a card. Times use the owner's zone. A re-arm updates the card text in place, a disarm closes the card, and reopening the item reopens it. The card awaits nobody. + +**Deferral card release gate (TRIG-7):** cards post live, but `KinChatService.act` refuses deferral-card taps (`deferralCardActionsReady = false`) until the owner-tap dispatcher from the owner-check gate exists. `Deferrals.act` already verifies the tap with the same `verifyOwnerTap` as the owner check. Before enabling taps: + +- the owner-check gate's dispatcher steps must land (chat act enqueues `widget.action`; `WakeupRunner` intercepts card actions without showing them to the model); +- `WakeupRunner` must run `Deferrals.act` for `deferral` actions, then `MemoryWriter.commitWakeup` (the commit re-arms through the cache hook), then queue `finish`. [Change] goes to the lead as an owner message about the item; +- production `MemoryWriterAuthority.resolve` must grant `kind: "deferral_card"` (item id, action `remind`) only after verifying the claimed owner tap. With that grant, the writer lets `on_due` change, and only to `remind`; +- web and mobile must render the native card and its closed state. **Flow for `start`** (`kin_deferral_runs.state`): @@ -223,7 +234,8 @@ armed ──heads_up fire──▶ recheck ──changed──▶ asked (decis ``` - **The recheck is code.** It runs `gh api` reads for every GitHub link plus a read of the memory item. Any difference from the snapshot means "changed": an issue closed, an assignee added, another linked PR, or the item superseded. The ask then names what changed. -- **Late.** If the machine woke after `due`, the `heads_up` fire is skipped. The `due` fire posts the same card with "This was due at 9:00" and a 30-minute grace from now; silence still means go. +- **Late.** If the machine woke after `due`, the `heads_up` fire is skipped. A `due` fire within the 30-minute grace window posts the same card with "This was due at 9:00" and a grace from now; silence still means go. An older fire asks instead of starting. +- **Stale fires.** Fires wait in the inbox until TRIG-8 consumes them. TRIG-8 drops a fire whose run row is `disarmed` or whose `due_at` no longer equals the fire's due instant. - **Level and stop switch.** Below L2, or with the org's stop switch on, `start` becomes `ask`. Silence never starts work then. - **Idempotent start.** Starting is a Work-class action keyed by `fireId`, so a replay can't start two workers. - **Bring it up early.** When a message touches the topic before the due time, the lead mentions it (LEAD, using the cache). The Monday morning brief lists deferrals due this week. @@ -501,7 +513,7 @@ Kin runs on one always-on machine, the **Kin host**. The laptop and phone are cl - **Scheduler:** a deferral due 09:00 +05:30 fires once at 09:00. Two ticks at the same instant give one inbox row. Advancing the clock 10 h with the scheduler stopped, then starting it, gives one inbox fire with `lateByMs = 10 h`; the deferral consumer (TRIG-8) posts the "This was due at 9:00" card. Recurring downtime emits one stored slot, not every missed occurrence. - **Timezone:** with the server zone `UTC` and the org zone `Asia/Kolkata`, the dream fires at 21:30 UTC. A 09:00 routine in `America/New_York` stays at 09:00 across both DST transitions; weekdays are owner-local. Two orgs with different zones fire independently; changing one org's zone or routine times recomputes only its schedules. - **Sink:** a signed GitHub `pull_request` request through the real `ScheduledTaskService` gives exactly one inbox row and no thread launch. A replay gives `duplicate` and no new row. A bot-sender request gives `filtered`. A non-Kin task still launches normally. -- **Deferral:** unchanged recheck, then heads-up, then silence, then `started` at due. A linked issue closed before due leads to `asked`, and nothing starts. With the stop switch on, it asks. [Monday] re-arms to next Monday 09:00. +- **Deferral:** unchanged recheck, then heads-up, then silence, then `started` at due. A linked issue closed before due leads to `asked`, and nothing starts. With the stop switch on, it asks. [Monday] re-arms to next Monday 09:00. A `due` fire consumed two hours late asks; a queued fire for a disarmed or moved deferral is dropped. - **Dream:** a dream touching `rules.md` fails, and `main` is unchanged. A dream with one journal fold and one `decisions/` change opens two PRs, and only the auto one merges. - **Secret scan:** a journal line holding `ghp_` plus 36 characters blocks the entire commit, and the owner gets one typed notification without the value. - **Purge:** on a fixture repo, the file is gone from `git log --all -p`, a tombstone exists, and an audit row exists. diff --git a/packages/contracts/src/kinLead.ts b/packages/contracts/src/kinLead.ts index 3596dc22ab969..c3594ec11f9d0 100644 --- a/packages/contracts/src/kinLead.ts +++ b/packages/contracts/src/kinLead.ts @@ -142,6 +142,15 @@ export const WorkerReport = Schema.Struct({ }); export type WorkerReport = typeof WorkerReport.Type; +export const KinDeferralCard = Schema.Struct({ + itemId: KinMemoryItemId, + title: Schema.String, + dueAt: Schema.toEncoded(CanonicalUtcTimestamp), + onDue: Schema.Literals(["remind", "start", "ask", "chase"]), + text: Schema.String, +}); +export type KinDeferralCard = typeof KinDeferralCard.Type; + const EventBase = { orgId: KinOrgId, eventId: KinEventId,