Repository navigation
feat: durable streams, agent run queue, evals, token budgets - #404
Conversation
Six capabilities an AI workload needs from the backend, plus two
platform guarantees they rest on.
Durable streams. A `.stream()` procedure declared `{ durable: true }`
persists each chunk under a monotonic seq before it reaches a socket,
and its producer outlives the socket that opened it. A run is keyed by
(functionPath, args), so a reload replays the gap and continues, and a
second client with the same arguments attaches to the same transcript
instead of paying for a second generation. A run whose DO is evicted
mid-flight replays its prefix and then fails STREAM_INTERRUPTED rather
than silently re-running the handler, which would bill twice and
duplicate the tail. Wire: `chunk.seq` out, `stream.sinceChunk` in.
Agent run queue. `onConcurrentRun: "queue"` was documented and
degraded to "reject". It is now a real FIFO queue (five deep): a
parked run hibernates on a scoped waitForEvent, and the finishing
run's completion writes its terminal status AND hands the thread to
the next run in the same mutation, so there is no window in which the
thread is ownerless and a third run can jump the line. The wake is a
durable step; the waiter's own timeout covers a wake that can never
land.
Agent replies. An inbound trigger could start a run but never answer.
`AgentReplyRef` rides the run params, `defineAgent({ onReply })` fires
once on the final answer inside a durable step, and the email capture
plus threaded send ship as `@lunora/agent/reply`. Slack/GitHub/Discord
get the ref and the worker env; the framework knows where to reply,
the app holds the credential.
Evals. `recordEvaluation` takes an optional metrics handle and records
the score as a gauge alongside the span attributes -- span attributes
live in a bounded in-memory ring and vanish on hibernation, so the
metric is what can back a trend. The new Studio Evals page joins both
halves: durable trend, plus the individual verdicts with the trace
that earned each one.
Reactive RAG. `ragSyncTriggers` hangs re-indexing off the write:
a table trigger schedules an internal action, which embeds once the
mutation has committed. An edit that does not touch the indexed text
schedules nothing; clearing it removes the chunks.
Token budgets. A request limit is the wrong shape for a model call --
one call can cost a hundred tokens or a hundred thousand.
`tokenBudget` makes the unit tokens (or cents), spent in arrears
because that is when the cost is known.
Deterministic mutations. A mutation body now runs with Date.now()
frozen to the dispatch instant, Math.random() seeded, and fetch
refused. Sound because a mutation holds the single-writer gate;
queries interleave, so they keep the advisor lint and ctx.now instead.
Components. `defineComponent` + `defineSchemaExtension` already
worked and were undocumented, which for a contract is the same as not
existing. Now a concepts page, including what a component explicitly
does not get: no isolation from app data, no per-component config, no
component-scoped RLS, no version negotiation.
Not included: snapshot coherence for query subscriptions. A
client-side coherence window was built, measured, and reverted -- it
changes the delivery contract every adapter relies on, and only
coalesces same-tick frames, which React already batches. The real fix
needs a batch boundary on the wire; recorded as plans/333.
BREAKING CHANGE: `fetch` throws inside a mutation
(NETWORK_IN_MUTATION). Network I/O belongs in an action: a
transaction that awaits a third party cannot be atomic. Move the call
to an action, or schedule one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hGhKLpXkFj3aWUYhZmWQv
Reverts one feature and closes three leak paths the audit found. Deterministic mutations, reverted. `withDeterministicScope` captured and restored `globalThis` around every mutation. The soundness argument — a mutation holds the DO's single-writer gate — is per Durable Object, and workerd hosts many DOs of one class per isolate. Two interleaved scopes therefore corrupt the save/restore stack and leave the isolate permanently patched: a frozen clock and a throwing `fetch` for every shard, query, alarm, and telemetry flush on it. Reproduced, then reverted whole; the sound shape (per-context injection) is recorded in plans/334. Durable streams no longer cache an answer. A finished run was replayed to any later caller with the same arguments, which made the feature a 24-hour response cache — including for a failed run, re-served with no retry path. Sharing is now scoped to a run still IN FLIGHT; a caller resuming a transcript it already holds still gets the tail. An eviction no longer wedges the key either: a dead run with nobody resuming it is reclaimed rather than answering STREAM_INTERRUPTED until its TTL expires. Durable stream runs are per-identity. The run key now includes the socket's verified identity, so two users asking the same question never share a transcript. An attach never drives the handler, so a shared run would also skip the procedure's RLS middleware. Durable stream storage is bounded. Each run stores its own `ttl_ms` — one procedure's sweep was deleting every other procedure's transcripts — chunks are capped, the per-chunk run-row UPDATE is gone (nothing read it mid-run), and a sink whose socket refused a frame is dropped instead of retried per chunk. The agent run queue no longer leaks. A run that ended while still parked kept its slot forever, and five of those exhausted the depth cap permanently; the completion mutation now releases a non-owner's row. Ownership transfers before the wake is sent, so an instance terminated while parked left the thread owned by a workflow that would never resume; a thread untouched past the dequeue window is now reclaimable. The park moved inside the try block so a timed-out wait still runs the completion, and a failing run's error survives the handoff instead of being cleared. Token budgets charge oversized calls. `record` forwarded the raw count to the limiter, which throws past capacity — so the one call a budget exists to catch escaped it entirely and replaced the caller's error. Clamped to capacity. Also: the Node capability entry claimed durable streams it does not implement (now `unsupported`), the client trusts the server's `seq` rather than the caller's `durable` flag, `sinceChunk` is validated before it can truncate a stream, the RAG sync action is typed instead of `unknown`, and the Evals trace drill-down is actually wired. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018hGhKLpXkFj3aWUYhZmWQv
✅ Deploy Preview for lunorash ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Warning Review limit reached
Next review available in: 15 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (31)
📒 Files selected for processing (9)
WalkthroughThe pull request adds durable streams, queued agent execution and replies, RAG synchronization, token budgets, evaluation telemetry and Studio views, packaged-component documentation, and CLI skill validation. ChangesDurable streams
Queued agent runs and replies
Evaluation telemetry and Studio
RAG synchronization and token budgets
Documentation and tooling
Estimated code review effort: 5 (Critical) | ~120 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Thank you for following the naming conventions! 🙏 |
|
Thank you for confirming the Contributor License Agreement! 🙏 |
|
React Doctor found no new issues. 🎉 Reviewed by React Doctor for commit |
There was a problem hiding this comment.
Actionable comments posted: 11
🧹 Nitpick comments (5)
packages/agent/src/component.ts (1)
222-265: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueQueue positions restart at 0 after the queue drains; confirm this stays FIFO-safe.
positionis allocated asmax(position) + 1over the rows currently queued. When the queue empties, the next enqueue starts again at 0. Ordering is only ever compared inside one snapshot of rows, so FIFO holds today. The invariant is implicit, so a future reader could assumepositionis globally monotonic per thread and compare rows across dequeues.Consider stating that invariant in the field doc on
position, or allocating from the thread row instead so the counter never restarts.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/agent/src/component.ts` around lines 222 - 265, Document the queue-position invariant at the RUN_QUEUE_TABLE position field: positions are FIFO ordering values scoped to the currently queued rows and may restart at 0 after the queue drains, rather than being globally monotonic per thread. Keep the existing max(position) + 1 allocation in enqueueRun unchanged.packages/studio/src/features/agents/agents-panel.tsx (1)
184-185: 🚀 Performance & Scalability | 🔵 Trivial | 💤 Low valuePrecompute the queue counts once, and note the shared row cap.
queueDepthscansqueuedRunson every call, and the render calls it twice per thread row (line 244 and line 248). WithTHREAD_LIMITat 100 for both reads, that is up to 20,000 comparisons per render. A single count map removes the repeated scan and the duplicate call.Also note that the queue read is capped at 100 rows across all threads, not per thread. The per-thread cap is 5, so a deployment with more than 20 threads holding queued runs shows understated counts.
♻️ Proposed refactor
- const queuedRuns = Array.isArray(queuePage?.rows) ? queuePage.rows : []; - const queueDepth = (threadKey: string): number => queuedRuns.filter((row) => readString(row, "threadKey") === threadKey).length; + const queuedRuns = Array.isArray(queuePage?.rows) ? queuePage.rows : []; + const queueDepths = new Map<string, number>(); + + for (const row of queuedRuns) { + const threadKey = readString(row, "threadKey"); + + if (threadKey !== undefined) { + queueDepths.set(threadKey, (queueDepths.get(threadKey) ?? 0) + 1); + } + }- <TableCell className="tabular-nums"> - {queueDepth(key) === 0 ? ( - <span className="text-muted-foreground">—</span> - ) : ( - <Badge data-testid={`agents-thread-queued-${key}`} variant="warning"> - {queueDepth(key)} - </Badge> - )} - </TableCell> + <TableCell className="tabular-nums"> + {queued === 0 ? ( + <span className="text-muted-foreground">—</span> + ) : ( + <Badge data-testid={`agents-thread-queued-${key}`} variant="warning"> + {queued} + </Badge> + )} + </TableCell>Declare
const queued = queueDepths.get(key) ?? 0;next toconst statusinside the row callback.Also applies to: 243-251
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/studio/src/features/agents/agents-panel.tsx` around lines 184 - 185, Replace the per-call queuedRuns.filter logic in the queue-depth setup with a single Map that counts rows by threadKey, then read the cached count once per thread row alongside status (for example, queued = queueDepths.get(key) ?? 0) and reuse it for both render decisions. Preserve the existing shared 100-row fetch behavior, and account for the documented cap when interpreting per-thread counts.packages/agent/src/reply.ts (1)
35-51: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd unit tests for the reply helpers.
captureEmailReplyRefandbuildReferenceshold the RFC 5322 threading logic, and both have clear branch pairs: missingmessageId, and present versus absentreferences. No test file accompanies this new module.Add
packages/agent/__tests__/reply.test.tscovering both helpers.As per coding guidelines: "Keep package source in the standard structure:
src/index.tsfor main exports and__tests__/for Vitest tests using.test.tsor.spec.tsfilenames."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/agent/src/reply.ts` around lines 35 - 51, Add packages/agent/__tests__/reply.test.ts with Vitest unit tests for captureEmailReplyRef and buildReferences. Cover undefined messageId returning undefined, preserving fields when messageId exists, appending messageId to existing references, and using messageId alone when references is absent; import the helpers through the package’s standard export path.Source: Coding guidelines
packages/ratelimit/src/token-budget.ts (1)
91-93: 🚀 Performance & Scalability | 🔵 Trivial | 🏗️ Heavy liftAvoid the duplicate bucket read on every charge.
getValuereads the bucket beforelimiter.limitreads it again. If theRateLimitStoreis remote, everyrecordcall adds an unnecessary round trip. Expose the configured effective cap without reading bucket state, or move cap resolution into the limiter operation.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ratelimit/src/token-budget.ts` around lines 91 - 93, Update the record/charge flow around limiter.getValue and limiter.limit to eliminate the duplicate bucket read on each call. Resolve the effective capacity from limiter configuration without fetching bucket state, or move that resolution into limiter.limit, while preserving the existing Math.min token count and effective-cap behavior.packages/server/src/builder/index.ts (1)
263-274: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winReuse
DurableStreamOptionsin this signature.Line 263 repeats the durable options shape. Use
DurableStreamOptionshere, as the public builder type does. This prevents contract drift when durable options gain fields.As per path instructions: “Follow DRY principles.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/server/src/builder/index.ts` around lines 263 - 274, Update the stream builder signature around the durable option parameter to use the existing DurableStreamOptions type instead of repeating the inline object shape. Preserve the current optional parameter behavior and durable normalization logic.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/docs/src/content/docs/concepts/components.mdx`:
- Around line 43-44: Make both TypeScript examples in
apps/docs/src/content/docs/concepts/components.mdx self-contained: at lines
43-44, define or import makeVotingApi, or remove that middleware from the
minimal example; at lines 58-61, import defineSchema, defineTable, and v from
`@lunora/server`.
In `@packages/agent/package.json`:
- Around line 69-72: Reorder the ./reply export entry in the package exports map
so it appears before ./sandbox and the keys remain alphabetical. After updating
the manifest, run pnpm run lint:package-json to validate canonical ordering.
In `@packages/agent/src/agent-loop.ts`:
- Around line 1086-1094: Remove the early persistUserTurn() call immediately
after the bootstrap replacement handling, and retain the existing call inside
the try block after awaitDequeue. Ensure user-turn persistence occurs only after
the run owns the thread, using the existing persistUserTurn symbol and queue
flow.
- Around line 1040-1049: Move the run-completion and queue-handoff doc comment
from above persistUserTurn to directly above finishRun, leaving persistUserTurn
with only its user-turn documentation.
In `@packages/ai/src/rag/sync.ts`:
- Around line 141-149: Update the sync logic around sourceId and the early
text-unchanged return to compute the previous ID from event.previous and the
current ID from event.doc. When the source ID or text changes, schedule deletion
for the previous ID and schedule the current document content for the current
ID; retain the no-op behavior only when both are unchanged.
In `@packages/do/src/shard-do.ts`:
- Around line 747-755: Add a persisted-byte ceiling alongside
MAX_DURABLE_STREAM_CHUNKS, and update produceDurableStream to track accumulated
chunk bytes with a bytes counter next to seq. Before persisting each chunk,
enforce both the chunk-count and byte ceilings, failing whichever limit is
reached first; keep the existing sequence-based behavior for normal chunks.
- Around line 7716-7757: Guard both the initial readStreamRun header lookup and
the __stream_chunks read inside the replay() closure in attachDurableStream.
Treat read failures as no existing run/chunks so the normal claim path can
proceed, or explicitly send an error and invoke detach(); ensure no exception
escapes before the stream receives completion/error and its streamCancellers
entry is cleaned up.
- Around line 7718-7725: Update the run-key construction around
readAttachment(ws) so authenticated callers continue using userId, while
anonymous callers use the socket’s clientId. When neither identity is available,
generate a per-socket unique key rather than falling back to an empty owner,
ensuring anonymous sockets never share runs while preserving the existing
functionPath and stableWireKey(args) components.
In `@packages/ratelimit/src/token-budget.ts`:
- Around line 91-93: Update the token-budget charging logic in record around
limiter.getValue and limiter.limit to ensure the count is always a positive
integer and never exceeds the enforced per-shard capacity. Reject unsupported
zero or fractional effective capacities before charging, including fractional
rate when capacity is absent, and derive the count from the shard-adjusted limit
when shards are configured. Add coverage for zero capacity, fractional capacity,
fractional rate without explicit capacity, and sharded limits.
- Around line 91-93: Update the token-budget flow around limiter.getValue and
limiter.limit to cap the charge at the effective per-shard capacity, dividing
(config.capacity ?? config.rate) by the configured shard count before applying
Math.min. Ensure the resulting count is a valid positive integer while
preserving reserve: true and the existing key/name arguments.
In `@packages/studio/src/features/evals/eval-scores.ts`:
- Around line 105-123: Update buildEvalCards so trend points calculate durable
statistics using the aggregate fields: minimum from point.min, maximum from
point.max, and mean from the total point.sum divided by total point.count.
Continue using point.last for latest and sparkline values, and retain the
existing run-score calculations when no trend points exist.
---
Nitpick comments:
In `@packages/agent/src/component.ts`:
- Around line 222-265: Document the queue-position invariant at the
RUN_QUEUE_TABLE position field: positions are FIFO ordering values scoped to the
currently queued rows and may restart at 0 after the queue drains, rather than
being globally monotonic per thread. Keep the existing max(position) + 1
allocation in enqueueRun unchanged.
In `@packages/agent/src/reply.ts`:
- Around line 35-51: Add packages/agent/__tests__/reply.test.ts with Vitest unit
tests for captureEmailReplyRef and buildReferences. Cover undefined messageId
returning undefined, preserving fields when messageId exists, appending
messageId to existing references, and using messageId alone when references is
absent; import the helpers through the package’s standard export path.
In `@packages/ratelimit/src/token-budget.ts`:
- Around line 91-93: Update the record/charge flow around limiter.getValue and
limiter.limit to eliminate the duplicate bucket read on each call. Resolve the
effective capacity from limiter configuration without fetching bucket state, or
move that resolution into limiter.limit, while preserving the existing Math.min
token count and effective-cap behavior.
In `@packages/server/src/builder/index.ts`:
- Around line 263-274: Update the stream builder signature around the durable
option parameter to use the existing DurableStreamOptions type instead of
repeating the inline object shape. Preserve the current optional parameter
behavior and durable normalization logic.
In `@packages/studio/src/features/agents/agents-panel.tsx`:
- Around line 184-185: Replace the per-call queuedRuns.filter logic in the
queue-depth setup with a single Map that counts rows by threadKey, then read the
cached count once per thread row alongside status (for example, queued =
queueDepths.get(key) ?? 0) and reuse it for both render decisions. Preserve the
existing shared 100-row fetch behavior, and account for the documented cap when
interpreting per-thread counts.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 08815997-fc8b-456a-9c9f-3c35e5b52a4a
⛔ Files ignored due to path filters (34)
api-snapshots/agent.api.mdis excluded by none and included by noneapi-snapshots/ai.api.mdis excluded by none and included by noneapi-snapshots/client.api.mdis excluded by none and included by noneapi-snapshots/do.api.mdis excluded by none and included by noneapi-snapshots/errors.api.mdis excluded by none and included by noneapi-snapshots/lunora.api.mdis excluded by none and included by noneapi-snapshots/platform.api.mdis excluded by none and included by noneapi-snapshots/ratelimit.api.mdis excluded by none and included by noneapi-snapshots/react.api.mdis excluded by none and included by noneapi-snapshots/server.api.mdis excluded by none and included by noneapi-snapshots/shard-engine.api.mdis excluded by none and included by noneapi-snapshots/studio.api.mdis excluded by none and included by noneapi-snapshots/testing.api.mdis excluded by none and included by nonepackages/agent/__tests__/agent-loop.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/agent-state-loop.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/component.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/loop-harness.tsis excluded by!**/__tests__/**and included bypackages/**packages/agent/__tests__/reply.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/run-queue.prototype.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/run-queue.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/skill.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/ai/__tests__/rag/sync.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/codegen/__tests__/discover-agents.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/codegen/__tests__/fixtures/simple/expected/_generated/shard.tsis excluded by!**/_generated/**,!**/__tests__/**and included bypackages/**packages/do/__tests__/shard-do.durable-stream.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/ratelimit/__tests__/token-budget.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/studio/__tests__/features/evals/eval-scores.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**plans/240-agent-run-queue-design.mdis excluded by none and included by noneplans/242-agent-reply-design.mdis excluded by none and included by noneplans/245-eval-runner-design.mdis excluded by none and included by noneplans/333-query-snapshot-coherence.mdis excluded by none and included by noneplans/334-mutation-determinism.mdis excluded by none and included by noneplans/README.mdis excluded by none and included by noneprotocol/README.mdis excluded by none and included by none
📒 Files selected for processing (42)
apps/docs/src/content/docs/concepts/components.mdxapps/docs/src/content/docs/concepts/realtime.mdxapps/docs/src/content/docs/meta.jsonapps/docs/src/content/docs/non-goals.mdxpackages/agent/package.jsonpackages/agent/src/agent-loop.tspackages/agent/src/component.tspackages/agent/src/index.tspackages/agent/src/paths.tspackages/agent/src/reply.prototype.tspackages/agent/src/reply.tspackages/agent/src/run-queue.prototype.tspackages/agent/src/types.tspackages/ai/src/rag/index.tspackages/ai/src/rag/sync.tspackages/client/src/lunora-client.tspackages/client/src/types.tspackages/codegen/src/emit.tspackages/do/src/shard-do.tspackages/errors/src/catalog.tspackages/platform/src/capabilities.tspackages/ratelimit/src/index.tspackages/ratelimit/src/token-budget.tspackages/react/src/use-stream.tspackages/server/src/builder/index.tspackages/server/src/builder/types.tspackages/server/src/index.tspackages/server/src/types.tspackages/shard-engine/src/ctx-db-migrations.tspackages/shard-engine/src/durable-stream.tspackages/shard-engine/src/index.tspackages/shard-engine/src/types.tspackages/studio/src/app/nav-labels.tspackages/studio/src/app/nav-types.tspackages/studio/src/app/studio.tsxpackages/studio/src/features/agents/agents-panel.tsxpackages/studio/src/features/evals/eval-scores.tspackages/studio/src/features/evals/evals-panel.tsxpackages/studio/src/locales/en.tspackages/testing/src/agent-harness.tspackages/testing/src/evaluation-telemetry.tspackages/testing/src/index.ts
💤 Files with no reviewable changes (2)
- packages/agent/src/run-queue.prototype.ts
- packages/agent/src/reply.prototype.ts
| "./reply": { | ||
| "types": "./dist/reply.d.ts", | ||
| "import": "./dist/reply.mjs" | ||
| }, |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Move ./reply before ./sandbox to keep the export keys sorted.
The exports map is alphabetical: ., ./channels, ./component, ./inbound, ./naming, ./skill-markdown, ./sandbox… The new ./reply entry sits between ./skill-markdown and ./sandbox, which breaks the order and will not survive the canonical sort. Run pnpm run lint:package-json after the move so vis sort-package-json validates the file.
As per coding guidelines: "After editing any manifest, run pnpm run lint:package-json so vis sort-package-json validates canonical key order."
♻️ Proposed fix
- "./skill-markdown": {
- "types": "./dist/skill-markdown.d.ts",
- "import": "./dist/skill-markdown.mjs"
- },
"./reply": {
"types": "./dist/reply.d.ts",
"import": "./dist/reply.mjs"
},
"./sandbox": {
"types": "./dist/sandbox.d.ts",
"import": "./dist/sandbox.mjs"
},
+ "./skill-markdown": {
+ "types": "./dist/skill-markdown.d.ts",
+ "import": "./dist/skill-markdown.mjs"
+ },🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/agent/package.json` around lines 69 - 72, Reorder the ./reply export
entry in the package exports map so it appears before ./sandbox and the keys
remain alphabetical. After updating the manifest, run pnpm run lint:package-json
to validate canonical ordering.
Source: Coding guidelines
Codecov Report❌ Patch coverage is ❌ Your patch status has failed because the patch coverage (72.99%) is below the target coverage (75.00%). You can increase the patch coverage or adjust the target coverage. Additional details and impacted files@@ Coverage Diff @@
## alpha #404 +/- ##
==========================================
- Coverage 87.09% 86.95% -0.15%
==========================================
Files 1172 1200 +28
Lines 63383 65254 +1871
Branches 15447 15958 +511
==========================================
+ Hits 55202 56739 +1537
- Misses 7654 7964 +310
- Partials 527 551 +24
🚀 New features to boost your workflow:
|
Merging this PR will improve performance by 29.53%
|
| Benchmark | BASE |
HEAD |
Efficiency | |
|---|---|---|---|---|
| ⚡ | pure diff (unchanged) — 10 rows |
368 µs | 246.7 µs | +49.17% |
| ⚡ | flat 3 primitives (the notify.send attribute shape) |
62.6 µs | 55.7 µs | +12.49% |
Tip
Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.
Comparing feat/ai-first-class (6b20985) with alpha (7a39c53)2
Footnotes
-
10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
-
No successful run was found on
alpha(c7474df) during the generation of this report, so 7a39c53 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩
The correctness fixes shipped in the previous commit; these are the structural ones both reviewers raised. The durable-stream state machine moves to @lunora/shard-engine. It touches SQLite through SqlExec, the transcript store next door, and one optional waitUntil — nothing Cloudflare-specific — so it had no business being 250 lines in the repo's largest file. `DurableStreamRunner` owns the run registry and the producer; `ShardDO` keeps only the socket adapter (run key, sink, cancel wiring). The split it had before ran along a persistence/orchestration seam that matched nothing: the store was host-neutral and the logic driving it was not, which is exactly how the Node capability entry came to describe a feature that host cannot reach. One wire vocabulary for both stream paths. `streamFrames(ws, id)` builds the four frames in one place; the ephemeral and durable paths had grown their own copies, and had already drifted on canceller cleanup. The error frame's shape especially wants one home, since the durable path persists what it sends and replays it to every later attach. `EnsureThreadOutcome` replaces a five-field bag of optional booleans whose three states were mutually exclusive. The union is exported, so the loop stops re-declaring the shape inline as a cast, `awaitDequeue` loses its `queued: boolean | undefined` parameter and its internal early-out, and `priorInstanceId` is non-optional exactly where it is read. One in-memory agent-runtime double instead of three. `loop-harness` already exported one and two suites shadowed it with near-copies, so adding the run-completion mutation meant patching the same handler three times — and missing a fourth copy in @lunora/testing entirely, which is how a shipped harness broke. The same goes for the `ctx.db` double two suites had byte-identical copies of. Net: 630 fewer lines of test scaffolding, and one place to change when the runtime grows a function. Also: the RAG sync action is a typed reference rather than `unknown`, so passing the wrong thing is a compile error instead of a silent no-op. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018hGhKLpXkFj3aWUYhZmWQv
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
packages/testing/src/agent-harness.ts (2)
257-266: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winReject completions without an explicit
instanceId.
HarnessThread.instanceIdis optional. If a thread has no instance ID, a completion that also omitsinstanceIdpassesthread.instanceId !== args["instanceId"]and patches terminal fields without ownership validation. Require a stringinstanceIdbefore comparing ownership.As per path instructions: “Ensure proper TypeScript types.”
Proposed fix
const completeRun = (args?: Record<string, unknown>): unknown => { + const instanceId = args?.["instanceId"]; + if (typeof instanceId !== "string") { + return {}; + } + const thread = threads.get(args?.["key"] as string); - if (!args || !thread || thread.instanceId !== args["instanceId"]) { + if (!thread || thread.instanceId !== instanceId) { return {}; }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/testing/src/agent-harness.ts` around lines 257 - 266, Update completeRun to require args.instanceId to be a string before performing the thread ownership check, rejecting completions that omit it or provide another type. Preserve the existing key and instance ownership validation, and use proper TypeScript narrowing so the subsequent comparison and field patching remain type-safe.Source: Path instructions
188-201: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick winReject unsupported concurrent runs in the harness.
ensureThreadaccepts a second instance as"continued"and overwritesinstanceId. This can hide concurrency bugs in tests. Reject concurrent instances explicitly instead of mutating the thread. Type the handler asEnsureThreadOutcome.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/testing/src/agent-harness.ts` around lines 188 - 201, Update ensureThread to reject a different instanceId when an existing thread is already active, rather than returning "continued" or mutating the stored instanceId. Preserve continuation for the same instance and type the handler result as EnsureThreadOutcome.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/cli/skills/lunora/SKILL.md`:
- Around line 80-81: Update the advisor CLI documentation near the --min-score
and --baseline references to show --min-score <score> with its valid 0–100
range, state that bare --baseline uses lunora.advisor.map.json, and document
that --baseline <map> selects a custom map.
---
Outside diff comments:
In `@packages/testing/src/agent-harness.ts`:
- Around line 257-266: Update completeRun to require args.instanceId to be a
string before performing the thread ownership check, rejecting completions that
omit it or provide another type. Preserve the existing key and instance
ownership validation, and use proper TypeScript narrowing so the subsequent
comparison and field patching remain type-safe.
- Around line 188-201: Update ensureThread to reject a different instanceId when
an existing thread is already active, rather than returning "continued" or
mutating the stored instanceId. Preserve continuation for the same instance and
type the handler result as EnsureThreadOutcome.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: ca4b84a6-26e2-41a1-be81-6a17fd610957
⛔ Files ignored due to path filters (9)
api-snapshots/agent.api.mdis excluded by none and included by noneapi-snapshots/shard-engine.api.mdis excluded by none and included by nonepackages/agent/__tests__/agent-loop.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/agent-state-loop.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/component.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/loop-harness.tsis excluded by!**/__tests__/**and included bypackages/**packages/agent/__tests__/run-queue.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**packages/agent/__tests__/skill.test.tsis excluded by!**/__tests__/**,!**/*.test.tsand included bypackages/**plans/README.mdis excluded by none and included by none
📒 Files selected for processing (10)
packages/agent/src/agent-loop.tspackages/agent/src/component.tspackages/agent/src/index.tspackages/agent/src/types.tspackages/cli/skills/README.mdpackages/cli/skills/lunora/SKILL.mdpackages/do/src/shard-do.tspackages/shard-engine/src/durable-stream-runner.tspackages/shard-engine/src/index.tspackages/testing/src/agent-harness.ts
🚧 Files skipped from review as they are similar to previous changes (5)
- packages/agent/src/index.ts
- packages/agent/src/component.ts
- packages/agent/src/agent-loop.ts
- packages/agent/src/types.ts
- packages/do/src/shard-do.ts
`plans/README.md` says a completed plan is deleted once shipped and its record lives in the index plus git history. 312 was the only file still present that had actually shipped — verified against live code rather than its own status line, since those have been wrong in both directions before: `isLiveForCompanion` is in `query-args.ts` and wired through `ctx-db-companions.ts` and `ctx-db-backfill.ts`. Its two spun-out follow-ups (314, 315) keep their own files. Everything else in `plans/` is genuinely TODO, a spike whose remaining work is open, or a reference doc gating unbuilt follow-ons — so nothing else qualifies. Two corrections found while checking: the index prose still claimed 312 was "the only one still open" while its own table row two paragraphs earlier said DONE, and the row's spun-out link pointed at 314's number with 315's filename. Also drops the wave-21 rows this branch had swept into its earlier commit from another session's uncommitted work in the same checkout. They stay in the working tree, uncommitted, where they belong. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018hGhKLpXkFj3aWUYhZmWQv
`StreamOptions` was written inline at both `.stream()` terminals; `QueueDatabase` was three levels of `Parameters` indexing off the builder to arrive at a type `@lunora/server` already exports as `DatabaseWriter`. Both derivations were correct and neither told the next reader what the type is. A hand-written structural stand-in for the writer was the obvious move and the wrong one — it did not match `DatabaseWriter` and broke the build, which is the argument for naming the real type rather than approximating it. Also records the ceiling the audit raised on durable streams: an attach replays a transcript, it does not re-run the handler, so the procedure's middleware chain runs once for the caller that started the run. That is why the run key is identity-scoped, and it belongs next to the option that turns sharing on. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018hGhKLpXkFj3aWUYhZmWQv
The emitted `executeStream` reads `registered.durable`, but the emitted `RegisteredLunoraFunction` — the type of the `LUNORA_FUNCTIONS` dispatch table every app generates — never declared it. So every project's `_generated/shard.ts` failed `tsc`, and the codegen suite stayed green throughout: emitted code is built as a string and asserted on as substrings, never compiled. `apps/playground` and `examples/expo` are where it surfaced, both only under the repo-wide typecheck. This is the failure mode AGENTS.md documents for this file and I walked straight into it. Verified the fix the way the guard asks: by typechecking two real apps' generated output, not the emitter's tests. Also reformats two files a later `eslint --fix` had re-broken after Prettier. `buildReferences` is now a statement body rather than a bare ternary, because the two tools disagreed about parenthesising it and each undid the other on every pass — ending the fight beats picking a winner. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018hGhKLpXkFj3aWUYhZmWQv
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/check-skill-mirrors.js`:
- Around line 210-213: Update the failure message in the checkSkillMirrors flow
to distinguish mirror mismatches from plugin-manifest lockstep mismatches. Since
checkPluginManifestLockstep only compares the Claude and Codex manifests, avoid
telling maintainers that both must agree with packages/cli/skills; provide
separate, accurate guidance for each failure source.
- Around line 180-203: Validate each parsed manifest in the loading loop before
field comparisons: require a non-null, non-array object and ensure every field
in the manifest contract is defined. Route validation failures through fail with
the existing path context and return, so malformed values—including null,
arrays, strings, and incomplete objects—cannot reach the LOCKSTEP_FIELDS or
author comparisons.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 926862ce-3797-48f2-9ea0-77c5dc9924c8
⛔ Files ignored due to path filters (24)
.agents/plugins/marketplace.jsonis excluded by none and included by none.claude-plugin/marketplace.jsonis excluded by none and included by noneAGENTS.mdis excluded by none and included by nonepackage.jsonis excluded by none and included by noneplugins/lunora/.claude-plugin/plugin.jsonis excluded by none and included by noneplugins/lunora/.codex-plugin/plugin.jsonis excluded by none and included by noneplugins/lunora/README.mdis excluded by none and included by noneplugins/lunora/hooks/hooks.jsonis excluded by none and included by noneplugins/lunora/scripts/verify-turn.mjsis excluded by none and included by noneplugins/lunora/scripts/verify-turn.test.mjsis excluded by none and included by noneplugins/lunora/skills/lunorais excluded by none and included by noneplugins/lunora/skills/lunora-create-packageis excluded by none and included by noneplugins/lunora/skills/lunora-deployis excluded by none and included by noneplugins/lunora/skills/lunora-functionsis excluded by none and included by noneplugins/lunora/skills/lunora-migration-helperis excluded by none and included by noneplugins/lunora/skills/lunora-performance-auditis excluded by none and included by noneplugins/lunora/skills/lunora-quickstartis excluded by none and included by noneplugins/lunora/skills/lunora-realtimeis excluded by none and included by noneplugins/lunora/skills/lunora-setup-authis excluded by none and included by noneplugins/lunora/skills/lunora-setup-hyperdriveis excluded by none and included by noneplugins/lunora/skills/lunora-setup-hyperdrive-globalis excluded by none and included by noneplugins/lunora/skills/lunora-setup-mailis excluded by none and included by noneplugins/lunora/skills/lunora-setup-scheduleris excluded by none and included by noneplugins/lunora/skills/lunora-setup-storageis excluded by none and included by none
📒 Files selected for processing (3)
packages/cli/skills/README.mdpackages/cli/skills/lunora/SKILL.mdscripts/check-skill-mirrors.js
🚧 Files skipped from review as they are similar to previous changes (2)
- packages/cli/skills/lunora/SKILL.md
- packages/cli/skills/README.md
Propagates the `durable` field added to the emitted dispatch type in c8b6240 out to the 13 committed example apps. Their `_generated/` had been left at the previous emitter output, so `RegisteredLunoraFunction` lacked `durable?: { ttlMs?: number }` and `executeStream` still returned the narrower shape. Nothing would have caught this. The vis tasks regenerate an app's generated dir via their `codegen` dependsOn before linting, so CI builds against fresh output while the stale files stay committed, and no gate diffs the two. The examples are read as reference code, so the staleness is user-visible even though every check is green. `apps/playground` is not included — its `lunora/_generated/` is gitignored. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7xe5PYB3zzmRrRod9eMTn
Nine comments; seven were right, two were not. The user turn was appended twice, and the first one landed before a parked run owned the thread — defeating the ordering the queue exists to provide, and contradicting the comment directly above it. Hoisting the call left the original in place. The keyed append meant no duplicate row, which is exactly why it was invisible. An unguarded store read after the ack could hang a consumer forever. `attach` reads `__stream_runs` after the host has already sent `ack`; on a pre-migration shard or a stub handle that throw escaped through a fire-and-forget catch, so the client held an acked stream that never settled and its host-side slot leaked. The attach now fails its sink, which is the one path that releases both. Anonymous callers shared one run. Falling back to a constant when the socket has no `userId` collapsed every anonymous caller onto one key — the second caller read the first one's transcript and the handler never ran for them. That is the same leak the identity scope closes for signed-in users, on the path with no identity to check. Keyed on the client's own stable id instead, so anonymous callers stay separate and can still resume their own run across a reload. The chunk ceiling bounded the wrong thing: 50,000 chunks of 1 MiB is ~50 GiB against a 10 GiB per-DO limit, so the cap could not prevent what its comment claimed. A byte ceiling now trips alongside it. A token budget on a sharded limit still threw. `getValue` reports the raw config while `limit` enforces `capacity / shards`, so clamping to the raw value exceeded the enforced capacity — leaving the oversized call uncharged, the exact escape the clamp was added to close. A RAG source id derived from a mutable column orphaned its chunks: when the id moved, the old ones stayed indexed and retrievable forever. Eval statistics were computed from each bucket's LAST sample, so a bucket holding 0 and 1 reported a minimum of 1 — wrong, and wrong in the flattering direction. Buckets carry min/max/sum/count for this. Declined: the `exports` map is not alphabetical and never was (`./skill-markdown` precedes `./sandbox`), and `vis sort-package-json` accepts it — export order is semantic, not cosmetic. The advisor-flag comment concerns another session's file. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018hGhKLpXkFj3aWUYhZmWQv
`JSON.parse` returns `null`, arrays, and strings as happily as objects,
and the lockstep check fed the result straight into field comparisons.
Each malformed shape defeated it differently: `null` threw a raw
TypeError out of a script that runs from `postinstall` — which surfaces
as every CI job failing in its setup step, with the cause invisible in
the job that reports it — while an array, a string, or `{}` left every
compared field `undefined` on both sides, so the manifests "matched" and
a check whose entire job is catching a malformed manifest passed one.
Each parsed manifest is now required to be a non-null, non-array object
carrying every field the comparison reads. Verified by feeding the real
check all four shapes.
The closing summary also described the manifest half as agreeing with
`packages/cli/skills`; it compares the two manifests with each other, so
it pointed maintainers at the wrong files.
Both from the automated review of #405, whose commit this branch now
carries.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hGhKLpXkFj3aWUYhZmWQv
|
This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
Six capabilities an AI workload needs from the backend, plus the component contract that was already built and undocumented.
What's in it
Durable streams.
.stream(handler, { durable: true })persists each chunk under a monotonicseqbefore it reaches a socket, and the producer outlives the socket that opened it. A reload resumes mid-generation instead of losing the work, and a second tab of the same user watches the same run rather than paying for a second one. Wire:chunk.seqout,stream.sinceChunkin.Agent run queue.
onConcurrentRun: "queue"was documented and silently degraded to"reject". It is now a real FIFO queue (five deep): a parked run hibernates on a scopedwaitForEvent, and the finishing run's completion writes its terminal status and hands the thread to the next run in the same mutation — so there is no window where the thread is ownerless and a third run can jump the line.Agent replies. An inbound trigger could start a run but never answer.
AgentReplyRefrides the run params,defineAgent({ onReply })fires once on the final answer inside a durable step, and@lunora/agent/replyships the email capture plus threaded send. Slack/GitHub/Discord get the ref and the workerenv— the framework knows where to reply, the app holds the credential.Evals.
recordEvaluationtakes an optionalctx.metricshandle and records the score as a gauge alongside the span attributes; span attributes live in a bounded in-memory ring, so the metric is what can back a trend across a hibernation. New Studio Evals page joins both halves.Reactive RAG.
ragSyncTriggershangs re-indexing off the write — a table trigger schedules an internal action, which embeds once the mutation has committed. An edit that doesn't touch the indexed text schedules nothing.Token budgets. A request limit is the wrong shape for a model call;
tokenBudgetmakes the unit tokens (or cents), spent in arrears because that is when the cost is known.Components.
defineComponent+defineSchemaExtensionalready worked and were undocumented, which for a contract is the same as not existing. Now a concepts page — including what a component explicitly does not get: no isolation from app data, no per-component config, no component-scoped RLS, no version negotiation.What was tried and rejected
Two things are deliberately not here, each with a plan recording the design:
plans/333— snapshot coherence for query subscriptions. A client-side coherence window was built and reverted: it changes the delivery contract every adapter relies on, and only coalesces same-tick frames, which React already batches. The real fix needs apokeStart/pokeEnd-style batch boundary on the wire.plans/334— runtime determinism for mutations.withDeterministicScopeswappedDate.now/Math.random/fetcharound every mutation. The soundness argument (a mutation holds the single-writer gate) is per Durable Object, and workerd hosts many DOs per isolate — two interleaved scopes corrupt the save/restore stack and leave the isolate permanently patched. Reproduced, then reverted whole. A sound version injects per-context.Review
Both
/thermospasses ran against the branch; the second commit is the fixes. The audit caught three criticals — the isolate poisoning above, durable streams behaving as a 24-hour response cache (a finished run was replayed to any later caller, including a failed one with no retry path), and two agent-queue leaks that could wedge a thread permanently. Also fixed: the Node capability entry claimed durable streams it does not implement,tokenBudget.recordthrew on exactly the oversized call it exists to catch, andsinceChunkwas trusted verbatim.Verification
Full suites green for
do,agent,shard-engine,client,server,react,ai,ratelimit,testing,studio,platform,codegen.api:checkgreen across 47 snapshots;lint:package-jsongreen. Rebased onto currentalpha.One pre-existing failure is unrelated and reproduces with this branch's changes stashed:
errors > catalog-registrationtimes out because its repo-wide scan now takes ~31s against a 10s limit.Summary by CodeRabbit