The state machine for kind=virtual Llm rows. Wires the schema added
in Stage 1 into something that can register, heartbeat, time out,
and relay inference tasks. The HTTP routes (Stage 3) plug into this.
Repository (extends ILlmRepository):
- create/update accept kind/providerSessionId/lastHeartbeatAt/status/
inactiveSince/type so VirtualLlmService can drive the lifecycle.
- findBySessionId(sessionId) — the reconnect lookup.
- findStaleVirtuals(cutoff) — heartbeat-stale rows for the GC sweep.
- findExpiredInactives(cutoff) — 4h-expired rows for deletion.
VirtualLlmService:
- register(): sticky-id-aware upsert. New names insert as kind=virtual/
status=active. Existing virtual rows from the same session reactivate
in place; existing inactive virtuals from a foreign session can be
adopted (sticky reconnect). Refuses to overwrite a public row or a
foreign session's still-active virtual.
- heartbeat(): bumps lastHeartbeatAt for every row owned by the
session; revives inactive rows.
- bindSession()/unbindSession(): in-memory map of sessionId → SSE
handle. Disconnect immediately flips owned rows to inactive AND
rejects any in-flight tasks for that session.
- enqueueInferTask(): pushes an `infer` task frame to the SSE handle,
returns a PendingTaskRef whose `done` resolves when the publisher
POSTs the result back. Streaming variant exposes onChunk(cb).
- completeTask/pushTaskChunk/failTask: route-side hooks called from
the result POST handler (lands in Stage 3).
- gcSweep(): flips heartbeat-stale active virtuals to inactive (90s
cutoff), deletes inactives past 4h. Idempotent.
Lifecycle constants live in this file (HEARTBEAT_TIMEOUT_MS=90s,
INACTIVE_RETENTION_MS=4h) so future stages can tune in one place.
18 new mocked-repo tests cover: register variants (insert, sticky
reconnect, refuse public-overwrite, refuse foreign-session, adopt
inactive-foreign), heartbeat-revive, unbind cascade, enqueue happy
path + 503 paths (no session, inactive, public-Llm), complete/fail/
streaming chunk fan-out, GC sweep flip + delete + idempotence.
mcpd suite: 819/819 (was 801, +18). Typecheck clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
