Files
platform/src/databases/officer_db/src/nudges/queries.ts
T
pastilhas 12c5e51ce4 nudger: a schedule that keeps a chat moving when nobody is watching
an agent told to record blockers and continue still stops at the end of a
turn, and at 3am nobody types the next message. this is the schedule that does.

the door already existed. `startClaudeTurn` takes `ws: null` — extracted that
way so command-hq could drive a turn over http — so this is a second caller of
an existing path rather than a new way into a live session. i had said the
platform lacked that; it did not.

the rule that decides the design: never speak while the agent is working. so
`every_seconds` is a FLOOR, not a metronome. when a nudge comes due and the
session is generating, the row is left alone and reconsidered next tick, which
means it fires as soon as the turn ends rather than sleeping through to the
next hour. a strict alarm would skip an agent that finished four minutes late
and leave it idle for the other fifty-six.

`isGenerating` unknown counts as BUSY. a sidecar that cannot answer might be
mid-turn, and interrupting one is the failure this exists to avoid.

matched on both sessionKey and claudeSessionId: officer's handle and the
transcript's filename are different ids, only the agent holds the mapping, and
a schedule stored against one would silently never match a live row keyed by
the other.

one nudge per (user, session) — a second schedule for one conversation is two
alarms for one sleeper. counted even when the turn fails to start, so a
refusal cannot become a tight loop. disables itself at the ceiling rather than
leaving a spent row armed. the tick starts in server.tsx rather than on first
use, because a schedule armed before a restart has to survive one.
2026-08-20 03:07:28 +00:00

81 lines
2.5 KiB
TypeScript

import { and, eq, lt, or, isNull, sql } from 'drizzle-orm';
import { db } from '../db';
import { nudges } from './schema';
import type { NudgeSelect } from '../types';
/** Create or replace the schedule for one session. Re-arming resets the count — it is a new night. */
export async function setNudge(params: {
userId: number;
sessionId: string;
message: string;
everySeconds: number;
maxCount: number;
}): Promise<NudgeSelect> {
const [row] = await db
.insert(nudges)
.values({ ...params, enabled: true, sentCount: 0, lastFiredAt: null })
.onConflictDoUpdate({
target: [nudges.userId, nudges.sessionId],
set: {
message: params.message,
everySeconds: params.everySeconds,
maxCount: params.maxCount,
enabled: true,
sentCount: 0,
lastFiredAt: null,
updatedAt: new Date(),
},
})
.returning();
return row!;
}
export async function getNudge(userId: number, sessionId: string): Promise<NudgeSelect | null> {
const [row] = await db
.select()
.from(nudges)
.where(and(eq(nudges.userId, userId), eq(nudges.sessionId, sessionId)))
.limit(1);
return row ?? null;
}
export async function cancelNudge(userId: number, sessionId: string): Promise<void> {
await db.delete(nudges).where(and(eq(nudges.userId, userId), eq(nudges.sessionId, sessionId)));
}
/**
* Everything the scheduler should consider this tick.
*
* Due means: enabled, under its ceiling, and either never fired or last fired at least `every_seconds`
* ago. Whether the session is actually IDLE is not asked here — that lives in the sidecar, not the
* database, and the scheduler checks it immediately before speaking.
*/
export async function dueNudges(now: Date = new Date()): Promise<NudgeSelect[]> {
return db
.select()
.from(nudges)
.where(
and(
eq(nudges.enabled, true),
lt(nudges.sentCount, nudges.maxCount),
or(
isNull(nudges.lastFiredAt),
lt(nudges.lastFiredAt, sql`${now} - (${nudges.everySeconds} * interval '1 second')`),
),
),
);
}
/** One nudge delivered. Disables itself on reaching the ceiling rather than leaving a spent row armed. */
export async function recordNudgeSent(id: number): Promise<void> {
await db
.update(nudges)
.set({
sentCount: sql`${nudges.sentCount} + 1`,
lastFiredAt: new Date(),
updatedAt: new Date(),
enabled: sql`${nudges.sentCount} + 1 < ${nudges.maxCount}`,
})
.where(eq(nudges.id, id));
}