Update stale docs#1404
Conversation
|
The latest Agentuity deployment details.
|
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (14)
📝 WalkthroughWalkthroughComprehensive documentation updates across agents, cookbooks, CLI references, SDK docs, and service guides: model identifier upgrades, schema-validation and type-safety improvements, wording clarifications, new/renamed CLI flags and commands, plus small runtime changes (signed cookie auth middleware) and expanded sandbox service scopes. Changes
|
📦 Canary Packages Publishedversion: PackagesInstallAdd to your {
"dependencies": {
"@agentuity/queue": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-queue-2.0.9-efde8b0.tgz",
"@agentuity/sandbox": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-sandbox-2.0.9-efde8b0.tgz",
"@agentuity/coder": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-coder-2.0.9-efde8b0.tgz",
"@agentuity/email": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-email-2.0.9-efde8b0.tgz",
"@agentuity/core": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-core-2.0.9-efde8b0.tgz",
"@agentuity/auth": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-auth-2.0.9-efde8b0.tgz",
"@agentuity/vector": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-vector-2.0.9-efde8b0.tgz",
"@agentuity/frontend": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-frontend-2.0.9-efde8b0.tgz",
"@agentuity/postgres": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-postgres-2.0.9-efde8b0.tgz",
"@agentuity/cli": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-cli-2.0.9-efde8b0.tgz",
"@agentuity/react": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-react-2.0.9-efde8b0.tgz",
"@agentuity/drizzle": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-drizzle-2.0.9-efde8b0.tgz",
"@agentuity/keyvalue": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-keyvalue-2.0.9-efde8b0.tgz",
"@agentuity/db": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-db-2.0.9-efde8b0.tgz",
"@agentuity/runtime": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-runtime-2.0.9-efde8b0.tgz",
"@agentuity/workbench": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-workbench-2.0.9-efde8b0.tgz",
"@agentuity/task": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-task-2.0.9-efde8b0.tgz",
"@agentuity/schema": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-schema-2.0.9-efde8b0.tgz",
"@agentuity/schedule": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-schedule-2.0.9-efde8b0.tgz",
"@agentuity/migrate": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-migrate-2.0.9-efde8b0.tgz",
"@agentuity/opencode": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-opencode-2.0.9-efde8b0.tgz",
"@agentuity/claude-code": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-claude-code-2.0.9-efde8b0.tgz",
"@agentuity/server": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-server-2.0.9-efde8b0.tgz",
"@agentuity/coder-tui": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-coder-tui-2.0.9-efde8b0.tgz",
"@agentuity/webhook": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-webhook-2.0.9-efde8b0.tgz",
"@agentuity/evals": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-evals-2.0.9-efde8b0.tgz"
}
}Or install directly: bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-queue-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-sandbox-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-coder-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-email-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-core-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-auth-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-vector-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-frontend-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-postgres-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-cli-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-react-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-drizzle-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-keyvalue-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-db-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-runtime-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-workbench-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-task-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-schema-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-schedule-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-migrate-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-opencode-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-claude-code-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-server-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-coder-tui-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-webhook-2.0.9-efde8b0.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/2.0.9-efde8b0/agentuity-evals-2.0.9-efde8b0.tgz |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (13)
apps/docs/src/web/content/cookbook/integrations/turborepo.mdx (1)
124-140:⚠️ Potential issue | 🟠 MajorPersist schema-complete history entries.
HistoryEntrySchemarequiressessionIdandtimestamp, but Line 125 stores entries without them and Line 126 then asserts the result asHistoryEntry[]. That can make the returnedhistoryfailTranslateOutputSchema/StateSchemavalidation despite the Line 140 type-safety claim.Proposed fix
- await ctx.thread.state.push('history', { text, translation, tokens, toLanguage, model }, 5); + const historyEntry: HistoryEntry = { + model, + sessionId: ctx.sessionId, + text, + timestamp: new Date().toISOString(), + tokens, + toLanguage, + translation, + }; + await ctx.thread.state.push('history', historyEntry, 5); const history = (await ctx.thread.state.get<HistoryEntry[]>('history')) ?? [];🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/integrations/turborepo.mdx` around lines 124 - 140, The history entries pushed via ctx.thread.state.push currently lack required fields from HistoryEntrySchema (sessionId and timestamp), so modify the code around the ctx.thread.state.push call to build each history entry with sessionId: ctx.sessionId and timestamp: Date.now() (or new Date().toISOString()) before pushing, and ensure the retrieval via ctx.thread.state.get is not blindly asserted as HistoryEntry[] but returns the schema-complete entries that satisfy TranslateOutputSchema/StateSchema; update the symbols: ctx.thread.state.push, HistoryEntrySchema, ctx.thread.state.get, and the TranslateOutputSchema-related return object accordingly.apps/docs/src/web/content/get-started/project-structure.mdx (1)
22-32:⚠️ Potential issue | 🟡 MinorTree indentation mixes tabs and spaces, breaking alignment.
Lines 23–25 begin with a tab followed by spaces (
\t │ ├──), while the surrounding rows (lines 22 and 26–31) use spaces only. Inside the fenced code block this renders as a misaligned tree with thesrc/agent/children shifted right of the other entries.✏️ Proposed fix
├── agent/ # Agent code - │ ├── index.ts # Agent registry (exports array of agents) - │ └── translate/ - │ └── index.ts # Default translation agent + │ ├── index.ts # Agent registry (exports array of agents) + │ └── translate/ + │ └── index.ts # Default translation agent ├── api/ # HTTP routes🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/get-started/project-structure.mdx` around lines 22 - 32, The code block in project-structure.mdx has mixed tabs and spaces causing misalignment for the agent/ subtree; normalize indentation by replacing the leading tab characters before "│ ├── index.ts" and "│ └── index.ts" (the lines showing agent/, index.ts and translate/index.ts) with the same number of spaces used by the other tree lines so the tree columns align consistently; ensure no tabs remain in that fenced code block.apps/docs/src/web/content/agents/schema-libraries.mdx (1)
279-295:⚠️ Potential issue | 🟡 MinorMove the optional marker onto the key for consistency with the idiomatic ArkType syntax.
Line 280 uses the recommended key-suffix form (
'nickname?': 'string'), but the nested object example on line 293 still uses the value-suffix form (tags: 'string[]?'). Per ArkType's official documentation, the key-suffix syntax is the idiomatic default and better reflects that optionality constrains key presence, not value type.✏️ Proposed fix
type({ user: { name: 'string', email: 'string.email', }, - tags: 'string[]?', + 'tags?': 'string[]', })🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/agents/schema-libraries.mdx` around lines 279 - 295, Update the nested-object example to use the key-suffix optional syntax for consistency: change the nested object definition inside the type(...) call so the optional "tags" is expressed as a key with a trailing ? (e.g., 'tags?') instead of making the value 'string[]?'; ensure you modify the object literal inside the type call that contains user and tags so it matches the existing `'nickname?': 'string'` style used earlier.apps/docs/src/web/content/reference/sdk-reference/events.mdx (1)
229-237:⚠️ Potential issue | 🟡 MinorRename
_ctxparameter toctxin the cleanup example.The handler declares
_ctx: AgentContextbut the function body usesctx.logger.info, creating an unresolved identifier. The sample won't compile as written.Proposed fix
const globalCompletedHandler = ( _eventName: 'agent.completed', completedAgent: Agent, - _ctx: AgentContext + ctx: AgentContext ): void => { ctx.logger.info('Observed completion', { agentName: completedAgent.metadata.name, }); };🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/sdk-reference/events.mdx` around lines 229 - 237, The example handler globalCompletedHandler declares the context parameter as _ctx: AgentContext but the function body uses ctx.logger.info, causing an unresolved identifier; rename the parameter from _ctx to ctx (type AgentContext) in the globalCompletedHandler signature so the ctx.logger.info call compiles, keeping the other parameters (event name, completedAgent: Agent) unchanged and preserving the metadata usage completedAgent.metadata.name.apps/docs/src/web/content/services/authentication.mdx (1)
24-25:⚠️ Potential issue | 🟡 MinorAdd
drizzle-ormto the install command.The install snippet only includes
@agentuity/authand@agentuity/drizzle, but the BYO adapter example imports fromdrizzle-orm/bun-sql. Whiledrizzle-ormis available as a transitive dependency, strict package managers (pnpm withstrictPeerDependencies, yarn with strict mode) require explicit declarations and will fail to resolve the deep import without it.Proposed fix
-bun add `@agentuity/auth` `@agentuity/drizzle` +bun add `@agentuity/auth` `@agentuity/drizzle` drizzle-ormAlso applies to: 143-164
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/authentication.mdx` around lines 24 - 25, Update the install command to explicitly include the drizzle-orm package so the deep import used in the BYO adapter example (e.g., imports from "drizzle-orm/bun-sql") resolves under strict package managers; modify the existing bun add invocation that currently lists "@agentuity/auth" and "@agentuity/drizzle" to also include "drizzle-orm" (and mirror the same change in the other occurrence around lines 143-164) so the docs and examples run without requiring transitive dependency resolution.apps/docs/src/web/content/cookbook/patterns/autonomous-research.mdx (1)
195-218:⚠️ Potential issue | 🟡 MinorSchema-validation failures are reported to the model as "No results found".
In both
searchWikipedia(Line 195-199) andgetArticle(Line 212-213), asafeParsefailure returns the same fallback text as the legitimate "zero results" path. If Wikipedia ever changes its response shape, the agent will loop believing the topic has no coverage, with no signal to the developer. Consider returning distinguishable text (and/or logging viactx.logger.warn) so the empty-result case and the validation-failure case are not conflated in the tool output fed back to the model.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/patterns/autonomous-research.mdx` around lines 195 - 218, The current safeParse failures in searchWikipedia (WikipediaSearchResponse.safeParse) and getArticle (WikipediaExtractResponse.safeParse) return the same fallback string as legitimate "no results" cases; change these branches to return distinguishable messages (e.g., "Schema validation failed for Wikipedia search/extract") and emit a warning via the available logger (use ctx.logger.warn or console.warn if ctx is not available) including the parse error details (the safeParse error object) and the raw response payload; keep the original "No results found." text only for genuine empty-result branches (results.length === 0 and missing page/extract) so the agent can differentiate validation failures from true empty results.apps/docs/src/web/content/reference/sdk-reference/observability.mdx (1)
257-265:⚠️ Potential issue | 🟡 MinorMark failed child spans as errors too.
If
db.getUser(userId)throws, the child span is ended withoutrecordException()orSpanStatusCode.ERROR, so the failing operation can appear as an unset child under an errored parent.Proposed nested span fix
const user = await ctx.tracer.startActiveSpan('fetch-user', async (childSpan) => { try { const result = await db.getUser(userId); childSpan.setStatus({ code: SpanStatusCode.OK }); return result; + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + childSpan.recordException(error instanceof Error ? error : new Error(message)); + childSpan.setStatus({ code: SpanStatusCode.ERROR, message }); + throw error; } finally { childSpan.end(); } });🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/sdk-reference/observability.mdx` around lines 257 - 265, The child span created via ctx.tracer.startActiveSpan('fetch-user', async (childSpan) => { ... }) currently only sets SpanStatusCode.OK on success and always ends the span in finally; modify the error path so that when db.getUser(userId) throws you call childSpan.recordException(err) and childSpan.setStatus({ code: SpanStatusCode.ERROR }) before rethrowing, ensuring error details are recorded on the child span (keep the childSpan.end() in finally). Use the existing childSpan, db.getUser, and SpanStatusCode symbols to locate and update the logic.apps/docs/src/web/content/services/storage/durable-streams.mdx (1)
442-459:⚠️ Potential issue | 🟡 MinorUse runtime validation instead of TypeScript type annotations for request parsing.
c.req.json<{ data: readonly ExportRow[] }>()only provides a type hint; it does not validate the incoming request. If thedatafield is missing or malformed, this code will fail silently or throw. Instead, add a validation step using.validator()middleware withc.req.valid('json'), or parse the result with a schema validator before destructuring.Examples of this pattern are documented in quickstart.mdx and middleware.mdx.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/storage/durable-streams.mdx` around lines 442 - 459, The handler for router.post('/export', async (c) => ...) currently uses c.req.json<{ data: readonly ExportRow[] }>() which is only a TS hint; replace this with runtime validation by calling c.req.valid('json') (or run the parsed body through your chosen schema validator) and validate that the result contains a data array of ExportRow-like objects before destructuring; ensure you reference the validated payload when writing to the stream returned by c.var.stream.create('export', ...) and keep the background write in c.waitUntil only after validation passes so malformed requests are rejected early.apps/docs/src/web/content/frontend/static-rendering.mdx (1)
10-47:⚠️ Potential issue | 🟡 MinorChange
agentuity bundletoagentuity buildfor consistency with the documentation and primary command name.Line 10 establishes
agentuity buildas the command for static rendering, but the example at line 45 usesagentuity bundle. Whilebundleis a valid alias for thebuildcommand, the rest of the documentation consistently usesbuild. Use the primary command name throughout for clarity.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/frontend/static-rendering.mdx` around lines 10 - 47, In the static-rendering example update the example command string "agentuity bundle # local build" to use the primary command name "agentuity build" so the final code block shows "agentuity build # local build" (keep the "agentuity deploy" line unchanged); this ensures consistency with the earlier mention of "agentuity build" and the rest of the docs.apps/docs/src/web/content/cookbook/patterns/server-utilities.mdx (2)
297-302:⚠️ Potential issue | 🟠 MajorValidate
STRIPE_WEBHOOK_SECRETbefore creating the source.Line 301 can silently configure
auth_valueasBearer undefined, creating a broken or unsafe ingestion source.Proposed fix
import { createSource } from '@agentuity/server'; import { client, logger } from '@/lib/agentuity-queues'; +const stripeWebhookSecret = process.env.STRIPE_WEBHOOK_SECRET; + +if (!stripeWebhookSecret) { + throw new Error('STRIPE_WEBHOOK_SECRET environment variable is required'); +} + const source = await createSource(client, 'webhook-queue', { name: 'stripe-webhooks', description: 'Receives Stripe payment events', auth_type: 'header', - auth_value: `Bearer ${process.env.STRIPE_WEBHOOK_SECRET}`, + auth_value: `Bearer ${stripeWebhookSecret}`, });🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/patterns/server-utilities.mdx` around lines 297 - 302, Before calling createSource for 'webhook-queue', validate process.env.STRIPE_WEBHOOK_SECRET and fail fast if missing so auth_value cannot become "Bearer undefined"; update the code around the createSource call (the auth_value construction) to check STRIPE_WEBHOOK_SECRET and throw or log an explicit error (or skip creation) when it's falsy, ensuring the source is only created when STRIPE_WEBHOOK_SECRET is present.
376-388:⚠️ Potential issue | 🟡 MinorAdd error handling for invalid session patch bodies.
SessionPatchSchema.parse()throws on invalid input and should be wrapped in a try-catch to return a 400 status code instead of surfacing validation failures as generic server errors.Suggested fix
router.post('/:id', async (c) => { const sessionId = c.req.param('id'); - const body: SessionPatch = SessionPatchSchema.parse(await c.req.json()); + let body: SessionPatch; + + try { + body = SessionPatchSchema.parse(await c.req.json()); + } catch { + return c.json({ error: 'Invalid request body' }, 400); + } const existing = await c.var.kv.get<ChatSession>('sessions', sessionId);🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/patterns/server-utilities.mdx` around lines 376 - 388, Wrap the call to SessionPatchSchema.parse(await c.req.json()) inside a try-catch in the router.post('/:id', async (c) => { ... }) handler so validation errors are caught, and on catch return a 400 response with the validation error details (e.g., use c.status(400) or c.json(..., 400) and include the error.message or error.format()). Keep the rest of the handler unchanged: only parse/validate the request body with SessionPatchSchema.parse inside the try block, and in the catch log the error via c.var.logger.warn or similar and return the 400 response.apps/docs/src/web/content/reference/sdk-reference/router.mdx (2)
200-231:⚠️ Potential issue | 🟡 MinorAlign external-backend guidance with the server-utilities page.
Line 202 now conflicts with
server-utilities.mdx, which documents standalone packages and manual@agentuity/serveraccess from external backends. Reframe this as the “centralized route” option rather than saying direct access is impossible.Proposed wording
-External backends cannot access Agentuity services directly. Create authenticated routes that expose storage operations, then call them via HTTP: +External backends can use standalone packages or `@agentuity/server` when they can safely hold an SDK key. If you want to centralize storage logic or avoid distributing SDK keys, create authenticated routes that expose storage operations, then call them via HTTP:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/sdk-reference/router.mdx` around lines 200 - 231, The guidance currently states "External backends cannot access Agentuity services directly" but should be reframed as a "centralized route" option and mention the alternative of using standalone `@agentuity/server`; update the prose around the example so it introduces this pattern as an option (e.g., "If you prefer not to install `@agentuity/server` in your external backend, you can create a centralized authenticated route that exposes storage operations — otherwise you can call `@agentuity/server` directly per the server-utilities page"), keep the example code (router.get('/:id', async (c) => ...), the getSession function using AGENTUITY_URL and STORAGE_API_KEY) as-is, and add a pointer to the server-utilities page for the manual `@agentuity/server` pattern.
440-461:⚠️ Potential issue | 🟠 MajorClose finite SSE streams explicitly and register abort handling before long-running work.
The example omits
stream.close(), which is part of the documented stream API and should be called when the stream is complete. Additionally,stream.onAbort()is registered after the long-running work finishes (line 458), making it unable to detect client disconnections during that async operation. RegisteronAbortbefore starting work and use a flag to exit early if the client disconnects.Proposed fix
router.get('/updates', sse(async (c, stream) => { - // Send initial connection message - await stream.writeSSE({ - event: 'connected', - data: JSON.stringify({ type: 'connected' }), - }); + let aborted = false; - // Stream agent progress updates - const updates = await longRunningAgent.run({ task: 'process' }); + // Clean up on client disconnect + stream.onAbort(() => { + aborted = true; + c.var.logger.info('Client disconnected'); + }); - for (const update of updates) { + try { + // Send initial connection message await stream.writeSSE({ - event: 'progress', - data: JSON.stringify({ type: 'progress', data: update }), + event: 'connected', + data: JSON.stringify({ type: 'connected' }), }); - } - // Clean up on client disconnect - stream.onAbort(() => { - c.var.logger.info('Client disconnected'); - }); + // Stream agent progress updates + const updates = await longRunningAgent.run({ task: 'process' }); + + for (const update of updates) { + if (aborted) break; + + await stream.writeSSE({ + event: 'progress', + data: JSON.stringify({ type: 'progress', data: update }), + }); + } + } finally { + stream.close(); + } }));🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/sdk-reference/router.mdx` around lines 440 - 461, Register the SSE abort handler before starting longRunningAgent.run and ensure the handler sets a flag to stop processing; call stream.close() when the stream is finished or when the abort flag is set. Specifically, in the router.get('/updates', sse(...)) handler register stream.onAbort(() => { aborted = true; c.var.logger.info('Client disconnected') }) prior to calling longRunningAgent.run, check the aborted flag inside the loop that consumes updates from longRunningAgent.run to exit early, and after the loop (or when aborting) call stream.close() to explicitly terminate the SSE stream.
🧹 Nitpick comments (16)
apps/docs/src/web/content/reference/sdk-reference/schema.mdx (1)
286-286: Good clarification of JSON Schema support scope.The addition of "Draft 7 subset" accurately sets expectations that full JSON Schema isn't supported.
Consider adding a subsection or note that lists which Draft 7 features are included in the subset (e.g., basic types, object properties, required fields, enums) and which are not (e.g., advanced keywords like
$ref,allOf,oneOf, conditional schemas). This would help users understand the conversion boundaries upfront.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/sdk-reference/schema.mdx` at line 286, Add a short subsection under the "Convert between `@agentuity/schema` schemas and a JSON Schema Draft 7 subset" sentence titled something like "Supported and unsupported Draft 7 features" that enumerates which Draft 7 features your converter covers (e.g., basic types, object properties, required, enums, arrays, min/max, format) and which it intentionally omits (e.g., $ref, allOf/anyOf/oneOf, not, dependentSchemas, conditional keywords like if/then/else, dynamic/unevaluated keywords), so readers immediately see conversion boundaries; keep the list concise and use bullet points or a two-column note to clearly separate supported vs unsupported features.apps/docs/src/web/content/services/index.mdx (1)
28-28: Good update! Consider aligning terminology with line 3.The introduction now correctly includes "identity" and better describes the platform's capabilities.
Minor consistency note: Line 3 uses "execution services" while this line uses "code execution" to describe the same concept (Coder and Sandbox sections). Consider using consistent terminology—"code execution" is clearer and more specific.
📝 Optional consistency improvement
If you prefer consistent terminology throughout the page, update line 3 to match:
-description: Identity, storage, messaging, observability, and execution services +description: Identity, storage, messaging, observability, and code execution🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/index.mdx` at line 28, The copy inconsistency: replace the phrase "execution services" with "code execution" (or vice versa) so terminology matches across the page; search for the string "execution services" (mentioned on line 3) and change it to "code execution" to align with the sentence that currently lists "identity, storage, messaging, observability, and code execution" and ensure Coder and Sandbox sections use the same term.apps/docs/src/web/content/reference/cli/configuration.mdx (1)
78-118: Secrets section largely duplicates the Environment Variables section — consider consolidating.Per the new callout at lines 70-72,
cloud env list/get/delete/push/pull/importalready handle both env vars and secrets, so the Get/Delete/Push/Pull/Import subsections under "Secrets" (lines 84-118) repeat the same commands shown earlier (lines 23-68) with no secret-specific behavior. This risks reader confusion about whether these are distinct commands.Consider trimming the Secrets section to just what differs:
List Secrets→env list --secretsSet a Secret→env set ... --secret- Runtime access note
…and drop the Get/Delete/Push/Pull/Import duplicates (or replace them with a single sentence pointing back to the Environment Variables section).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/cli/configuration.mdx` around lines 78 - 118, The Secrets subsection duplicates the Environment Variables commands (cloud env list/get/delete/push/pull/import) and should be trimmed: keep only the unique secret-specific notes and examples (the "List Secrets" example using --secrets and the "Set a Secret" example using --secret) plus a brief runtime access note, and remove the duplicated Get/Delete/Push/Pull/Import blocks or replace them with a single sentence linking readers back to the Environment Variables section; update headings "List Secrets" and "Set a Secret" accordingly and ensure the examples use the --secrets and --secret flags shown in the diff.apps/docs/src/web/content/frontend/index.mdx (1)
8-8: Consider whether "typed route calls" accurately represents the Frontend section focus.The hero copy changed from emphasizing "hooks" to "typed route calls." Since this is the landing page for React frontends and hooks are a fundamental React pattern, verify that this change doesn't obscure the React-specific features. The term "typed route calls" might suggest the RPC client (which works in any JavaScript environment) rather than React-specific capabilities.
💡 Alternative wording that includes both concepts
-Deploy React apps alongside your agents with typed route calls and authentication. +Deploy React apps alongside your agents with type-safe hooks, typed route calls, and authentication.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/frontend/index.mdx` at line 8, Update the hero copy string "Deploy React apps alongside your agents with typed route calls and authentication." to clearly reflect React-focused features: include "hooks" (or "React hooks") alongside "typed route calls" and "authentication" so readers know this landing page highlights React-specific patterns; modify the hero text to something like "Deploy React apps alongside your agents with React hooks, typed route calls, and authentication" (or similar phrasing) in the frontend index content to surface both concepts.apps/docs/src/web/content/cookbook/index.mdx (1)
105-105: Consider adding "Query" to the shortened title for clarity.The shortened title "Hono RPC + TanStack" removes "Query" from the full title. While surrounding content (the full title, description, and section heading "Client: Use with TanStack Query") makes it clear this refers to TanStack Query, the shortened title alone could be ambiguous given TanStack's multiple products (Query, Router, Table, etc.). Changing to "Hono RPC + TanStack Query" would make the shortened title self-contained and more explicit.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/index.mdx` at line 105, Update the shortened title string used in the cookbook frontmatter from "Hono RPC + TanStack" to "Hono RPC + TanStack Query" so the title is self-contained and unambiguous; locate the title attribute (title="Hono RPC + TanStack") in the file and replace it with title="Hono RPC + TanStack Query", leaving the surrounding frontmatter and other headings (e.g., the full title and "Client: Use with TanStack Query") unchanged.apps/docs/src/web/content/cookbook/patterns/cron-with-storage.mdx (1)
30-55: Nits: unusedStoryalias and||vs??for optional field.
- Line 30:
type Story = s.infer<typeof StorySchema>;is declared but never used in any of the surrounding route/frontend code blocks. If it's not meant to be illustrative for readers, drop it; otherwise add a short comment explaining its purpose.- Line 55:
story.url || \https://...`uses logical-OR while the rest of the PR leans on??for optional schema fields. Sinceurliss.optional(s.string())and onlyundefinedis expected here,story.url ?? ...` matches the surrounding style (and won't accidentally discard an empty-string URL if that ever became valid).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/patterns/cron-with-storage.mdx` around lines 30 - 55, Remove or document the unused Story type alias and switch the fallback from || to ??: either delete the unused "type Story = s.infer<typeof StorySchema>;" (or add a one-line comment explaining it’s illustrative) and replace the usage of "story.url || `https://news.ycombinator.com/item?id=${story.id}`" in the /digest handler with "story.url ?? `https://news.ycombinator.com/item?id=${story.id}`" so it preserves empty-string URLs and matches the codebase's optional-field style (references: Story, StorySchema, and the router.post('/digest' handler).apps/docs/src/web/content/cookbook/integrations/mastra.mdx (1)
94-104: Consider checkingresponse.okbefore parsing.If either
fetchreturns a non-2xx (rate limit, bad params, upstream outage),geo.json()/weather.json()will return an error body andGeoResponse.parse(...)/WeatherResponse.parse(...)will throw a zod validation error rather than surfacing the HTTP status. Since this snippet is the reference readers will copy, a quickif (!geo.ok) throw new Error(...)would model more defensive tool code.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/integrations/mastra.mdx` around lines 94 - 104, The fetch responses (geo and weather) are parsed without checking HTTP status, so non-2xx responses will cause opaque zod errors; update the code around the GeoResponse.parse and WeatherResponse.parse calls to check geo.ok and weather.ok after each fetch and, if false, throw a descriptive Error that includes the response.status (and optionally response.statusText or body text) before calling geo.json() / weather.json(); ensure the diagnostic mentions which request failed (geocoding vs forecast) so callers can see upstream HTTP errors instead of only zod validation failures.apps/docs/src/web/content/cookbook/integrations/langchain.mdx (1)
83-90: Nit:findLastis simpler than spread + reverse + find.Proposed simplification
- const lastAiMessage = [...result.messages] - .reverse() - .find((message): message is AIMessage => message instanceof AIMessage); + const lastAiMessage = result.messages.findLast( + (message): message is AIMessage => message instanceof AIMessage, + );Avoids the intermediate array allocation and reads more directly.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/integrations/langchain.mdx` around lines 83 - 90, Replace the reverse+find pattern with Array.prototype.findLast to avoid the intermediate array: change how lastAiMessage is computed from [...result.messages].reverse().find(...) to using result.messages.findLast((message): message is AIMessage => message instanceof AIMessage) and keep the existing conditional that returns lastAiMessage?.content or 'No response generated'; update the reference to lastAiMessage, result.messages, and AIMessage accordingly.apps/docs/src/web/content/community/inbound-email-agent.mdx (1)
206-230: Nit: inconsistent error log field names.The SDK-error path logs
{ error: message }(Line 221) while thecatchpath logs{ err: String(err) }(Line 228). Readers copying this pattern will end up with two different log keys for the same logical failure. Consider using{ error: ... }in both.♻️ Minor cleanup
} catch (err) { - c.var.logger.error('Failed to send reply', { err: String(err) }); + c.var.logger.error('Failed to send reply', { error: String(err) }); return c.json({ ...result, replySent: false, error: String(err) }, 500); }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/community/inbound-email-agent.mdx` around lines 206 - 230, The log field names are inconsistent between the inbound.reply error branch and the catch block; update the catch block that handles errors from inbound.reply (around the inbound.reply try/catch) to log using the same key used earlier ({ error: ... }) instead of { err: ... } — i.e., change the c.var.logger.error call inside the catch to include { error: String(err) } so both the SDK-error path and the exception path use the same error field, and return the same error shape in the c.json response.apps/docs/src/web/content/cookbook/patterns/web-exploration.mdx (1)
98-128: LGTM — step-limited termination and hardened summary extraction.Adding
isStepCount(maxSteps)alongsidehasToolCall('finish_exploration')is a good guardrail, and the runtime type checks ontoolCall.inputbefore assigningsummarycorrectly handle theToolCallunion across all tools. Consider noting in the prose thatmaxStepshas no lower bound inAgentInput— a caller passing0would cause the loop to stop before the first step.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/patterns/web-exploration.mdx` around lines 98 - 128, The code allows options.maxSteps to be 0 which makes isStepCount(maxSteps) terminate before any steps; update the explorer input handling so maxSteps has a sensible lower bound (minimum 1) before calling generateText: validate or clamp options.maxSteps when computing maxSteps (refer to the const maxSteps = options.maxSteps ?? 12 expression and the AgentInput type), ensuring callers passing 0 cannot disable stepping; add a short comment noting the enforced minimum for future readers.apps/docs/src/web/content/services/storage/object.mdx (1)
94-113: Consider tightening the output schema.Declaring both
dataanderroras optional means any combination (including both empty) passes validation. Consider modeling as a discriminated result (e.g.,s.union([s.object({ data: s.unknown() }), s.object({ error: s.string() })])) for a clearer contract. Non-blocking — this is illustrative example code.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/storage/object.mdx` around lines 94 - 113, The output schema in the createAgent call (schema.output) is too permissive because both data and error are optional; change schema.output in the createAgent('FileProcessor', ...) definition to a discriminated/result union instead of two optional fields — e.g., replace the current s.object({ data: s.unknown().optional(), error: s.string().optional() }) with a union of a success object (containing data) and an error object (containing error) so the handler's return values from handler (the file.exists() branch and the data return) validate correctly and unambiguously.apps/docs/src/web/content/services/queues.mdx (1)
233-250: Standalone example is cleaner, but consider showing error handling.Dropping
createApp/ctx.invokefor a plainQueueClientmatches the docs' direction, but since this is the only standalone example on the page, a brief note (or try/catch) about handlingQueueNotFoundError/ transient publish failures inside the loop would prevent silent partial sends when called from a long-running script. Optional.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/queues.mdx` around lines 233 - 250, The standalone example should handle publish errors to avoid silent partial deliveries; update the queueDailyReports function to wrap each queue.publish call in a try/catch that specifically handles QueueNotFoundError (and logs/handles transient failures like network timeouts or retries) and continues or retries as appropriate; reference QueueClient and queueDailyReports so reviewers can find the example and add a concise error handling strategy (e.g., logging the error with context and optionally retrying or skipping the failing user) inside the loop.apps/docs/src/web/content/cookbook/tutorials/understanding-agents.mdx (1)
59-96: Schema-validated Wikipedia response is a nice hardening.Switching to
URL+URLSearchParams(with proper encoding ofsrsearch) and validating viaWikipediaSearchResponseSchema.parse(...)removes the previous reliance onany-typed results. One minor note:origin: '*'is only meaningful for browser-origin CORS requests — it's harmless from server-sidefetch, but you could drop it to keep the example focused. Non-blocking.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/tutorials/understanding-agents.mdx` around lines 59 - 96, Remove the unnecessary "origin: '*'" query parameter from the URLSearchParams in the searchWikipedia tool since it only affects browser CORS and is redundant for server-side fetch; update the execute function where URL and URLSearchParams are constructed (the srsearch param and overall URL building inside searchWikipedia) to omit origin while keeping srsearch encoding and the response validation via WikipediaSearchResponseSchema.parse unchanged.apps/docs/src/web/content/services/sandbox/snapshots.mdx (1)
58-78: Show ametadatafield before demonstrating metadata substitution.The
--metadata VERSION=1.0.0option is introduced, but the YAML example has nometadatablock to substitute into. Adding a minimal block makes the option copy-pasteable.Proposed doc tweak
env: NODE_ENV: production + +metadata: + version: ${VERSION}Also applies to: 92-93
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/sandbox/snapshots.mdx` around lines 58 - 78, The example YAML shown for snapshots lacks a metadata section to demonstrate the new --metadata substitution; add a minimal metadata block (e.g., metadata: { VERSION: "1.0.0" } or metadata: followed by VERSION: 1.0.0) at the top of the YAML so the documented --metadata VERSION=1.0.0 option actually has a target to substitute into; update the YAML example in the snapshots.mdx file so the metadata key appears before env (or where appropriate) and matches the substitution name used in the text.apps/docs/src/web/content/reference/cli/opencode-plugin.mdx (1)
20-22: Bullet capitalization is inconsistent.Lines 21–22 start with lowercase ("slash commands…", "plugin tools…"), while Line 20 starts capitalized ("Agentuity Coder agents…"). Consider aligning all three.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/cli/opencode-plugin.mdx` around lines 20 - 22, The three bullet items under the plugin description are inconsistent in capitalization; update the bullet text so all start with sentence-style capitalization to match "Agentuity Coder agents…" — specifically change the bullets beginning "slash commands for Agentuity Coder, Cadence, cloud services, sandboxes, and memory" and "plugin tools for session dashboards and public memory sharing" to start with capitalized words ("Slash commands…" and "Plugin tools…") so all three list items are consistent.apps/docs/src/web/content/reference/cli/sandbox.mdx (1)
41-51: Consider listing new aliases in the Quick Reference.The top-level Aliases block (Lines 43–51) doesn't mention the newly introduced
ckpt(forcheckpoint),hibernate(forpause), orwake(forresume) aliases, which are only documented further down (Lines 251 and 696). Adding them here would keep the quick reference complete.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/cli/sandbox.mdx` around lines 41 - 51, Update the top-level Aliases quick reference to include the newly introduced shorthand commands by adding entries for `ckpt` as an alias for `checkpoint` and `hibernate`/`wake` as aliases for `pause`/`resume` respectively so the quick reference matches the later detailed docs; specifically, augment the Aliases block that currently lists `sb`, `rm`/`delete`, `fs`/`files`, `get`/`show`/`info`, `list`/`ls`, and `create`/`new` to also show `ckpt` → `checkpoint`, `hibernate` → `pause`, and `wake` → `resume` (these correspond to the commands documented later around the `sandbox checkpoint`, `sandbox pause`, and `sandbox resume` sections).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: eb0dd837-67d9-4b9d-b27c-ca2ae76476f1
📒 Files selected for processing (114)
apps/docs/src/web/components/docs/nav-data.tsapps/docs/src/web/content/agents/ai-gateway.mdxapps/docs/src/web/content/agents/ai-sdk-integration.mdxapps/docs/src/web/content/agents/calling-other-agents.mdxapps/docs/src/web/content/agents/creating-agents.mdxapps/docs/src/web/content/agents/events-lifecycle.mdxapps/docs/src/web/content/agents/schema-libraries.mdxapps/docs/src/web/content/agents/standalone-execution.mdxapps/docs/src/web/content/agents/state-management.mdxapps/docs/src/web/content/agents/streaming-responses.mdxapps/docs/src/web/content/agents/when-to-use.mdxapps/docs/src/web/content/community/inbound-email-agent.mdxapps/docs/src/web/content/cookbook/index.mdxapps/docs/src/web/content/cookbook/integrations/chat-sdk.mdxapps/docs/src/web/content/cookbook/integrations/claude-agent.mdxapps/docs/src/web/content/cookbook/integrations/langchain.mdxapps/docs/src/web/content/cookbook/integrations/mastra.mdxapps/docs/src/web/content/cookbook/integrations/nextjs.mdxapps/docs/src/web/content/cookbook/integrations/openai-agents.mdxapps/docs/src/web/content/cookbook/integrations/tanstack-start.mdxapps/docs/src/web/content/cookbook/integrations/turborepo.mdxapps/docs/src/web/content/cookbook/patterns/autonomous-research.mdxapps/docs/src/web/content/cookbook/patterns/background-tasks.mdxapps/docs/src/web/content/cookbook/patterns/chat-with-history.mdxapps/docs/src/web/content/cookbook/patterns/choosing-built-in-agents-for-a-coder-session.mdxapps/docs/src/web/content/cookbook/patterns/creating-coder-sessions-with-sdk.mdxapps/docs/src/web/content/cookbook/patterns/creating-loop-mode-coder-sessions.mdxapps/docs/src/web/content/cookbook/patterns/cron-with-storage.mdxapps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdxapps/docs/src/web/content/cookbook/patterns/llm-as-a-judge.mdxapps/docs/src/web/content/cookbook/patterns/observing-a-coder-session-through-the-hub.mdxapps/docs/src/web/content/cookbook/patterns/preparing-coder-sessions-for-remote-attach.mdxapps/docs/src/web/content/cookbook/patterns/product-search.mdxapps/docs/src/web/content/cookbook/patterns/server-utilities.mdxapps/docs/src/web/content/cookbook/patterns/tailwind-setup.mdxapps/docs/src/web/content/cookbook/patterns/using-workspaces-to-reuse-repos-skills-and-agent-selection.mdxapps/docs/src/web/content/cookbook/patterns/web-exploration.mdxapps/docs/src/web/content/cookbook/patterns/webhook-handler.mdxapps/docs/src/web/content/cookbook/tutorials/rag-agent.mdxapps/docs/src/web/content/cookbook/tutorials/understanding-agents.mdxapps/docs/src/web/content/frontend/authentication.mdxapps/docs/src/web/content/frontend/index.mdxapps/docs/src/web/content/frontend/rpc-client.mdxapps/docs/src/web/content/frontend/static-rendering.mdxapps/docs/src/web/content/get-started/app-configuration.mdxapps/docs/src/web/content/get-started/installation.mdxapps/docs/src/web/content/get-started/project-structure.mdxapps/docs/src/web/content/get-started/quickstart.mdxapps/docs/src/web/content/reference/cli/ai-commands.mdxapps/docs/src/web/content/reference/cli/claude-code-plugin.mdxapps/docs/src/web/content/reference/cli/configuration.mdxapps/docs/src/web/content/reference/cli/debugging.mdxapps/docs/src/web/content/reference/cli/deployment.mdxapps/docs/src/web/content/reference/cli/development.mdxapps/docs/src/web/content/reference/cli/getting-started.mdxapps/docs/src/web/content/reference/cli/git-integration.mdxapps/docs/src/web/content/reference/cli/index.mdxapps/docs/src/web/content/reference/cli/monitoring.mdxapps/docs/src/web/content/reference/cli/opencode-plugin.mdxapps/docs/src/web/content/reference/cli/sandbox.mdxapps/docs/src/web/content/reference/cli/storage.mdxapps/docs/src/web/content/reference/github-app.mdxapps/docs/src/web/content/reference/gravity-network.mdxapps/docs/src/web/content/reference/index.mdxapps/docs/src/web/content/reference/migration-guide.mdxapps/docs/src/web/content/reference/sdk-reference/advanced.mdxapps/docs/src/web/content/reference/sdk-reference/agents.mdxapps/docs/src/web/content/reference/sdk-reference/application-entry.mdxapps/docs/src/web/content/reference/sdk-reference/coder.mdxapps/docs/src/web/content/reference/sdk-reference/communication.mdxapps/docs/src/web/content/reference/sdk-reference/context-api.mdxapps/docs/src/web/content/reference/sdk-reference/email-service.mdxapps/docs/src/web/content/reference/sdk-reference/events.mdxapps/docs/src/web/content/reference/sdk-reference/observability.mdxapps/docs/src/web/content/reference/sdk-reference/queue-service.mdxapps/docs/src/web/content/reference/sdk-reference/router.mdxapps/docs/src/web/content/reference/sdk-reference/sandbox-service.mdxapps/docs/src/web/content/reference/sdk-reference/schedule-service.mdxapps/docs/src/web/content/reference/sdk-reference/schema.mdxapps/docs/src/web/content/reference/sdk-reference/storage.mdxapps/docs/src/web/content/reference/sdk-reference/task-service.mdxapps/docs/src/web/content/reference/standalone-packages.mdxapps/docs/src/web/content/routes/calling-agents.mdxapps/docs/src/web/content/routes/cron.mdxapps/docs/src/web/content/routes/explicit-routing.mdxapps/docs/src/web/content/routes/http.mdxapps/docs/src/web/content/routes/middleware.mdxapps/docs/src/web/content/routes/sse.mdxapps/docs/src/web/content/services/authentication.mdxapps/docs/src/web/content/services/coder.mdxapps/docs/src/web/content/services/database/drizzle.mdxapps/docs/src/web/content/services/database/index.mdxapps/docs/src/web/content/services/database/postgres.mdxapps/docs/src/web/content/services/email.mdxapps/docs/src/web/content/services/index.mdxapps/docs/src/web/content/services/observability/index.mdxapps/docs/src/web/content/services/observability/logging.mdxapps/docs/src/web/content/services/observability/sessions-debugging.mdxapps/docs/src/web/content/services/observability/tracing.mdxapps/docs/src/web/content/services/observability/web-analytics.mdxapps/docs/src/web/content/services/oidc-provider.mdxapps/docs/src/web/content/services/queues.mdxapps/docs/src/web/content/services/sandbox/index.mdxapps/docs/src/web/content/services/sandbox/sdk-usage.mdxapps/docs/src/web/content/services/sandbox/snapshots.mdxapps/docs/src/web/content/services/storage/custom.mdxapps/docs/src/web/content/services/storage/durable-streams.mdxapps/docs/src/web/content/services/storage/index.mdxapps/docs/src/web/content/services/storage/key-value.mdxapps/docs/src/web/content/services/storage/object.mdxapps/docs/src/web/content/services/storage/vector.mdxapps/docs/src/web/content/services/tasks.mdxapps/docs/src/web/content/services/webhooks.mdxpackages/core/src/services/sandbox/api-reference.ts
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (16)
- GitHub Check: Windows WSL CLI Smoke Test
- GitHub Check: Build
- GitHub Check: Queue SDK Tests
- GitHub Check: Framework Integration Tests (TanStack & Next.js)
- GitHub Check: Queue CLI Tests
- GitHub Check: Sandbox CLI Tests
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Package Installation & Usage Test
- GitHub Check: Postgres SSL Integration Test
- GitHub Check: Template Integration Tests
- GitHub Check: Pack & Upload
- GitHub Check: Cloud Deployment Tests
- GitHub Check: Storage CLI Tests
- GitHub Check: Standalone Agent Test
- GitHub Check: SDK Integration Test Suite
- GitHub Check: Agentuity Deployment
🧰 Additional context used
📓 Path-based instructions (4)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use Biome as code formatter with tabs (width 3), single quotes, semicolons, lineWidth 100, and trailingCommas es5
Files:
apps/docs/src/web/components/docs/nav-data.tspackages/core/src/services/sandbox/api-reference.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx}: Use TypeScript Strict mode with ESNext target and bundler moduleResolution
UseStructuredErrorfrom@agentuity/corefor error handling
Files:
apps/docs/src/web/components/docs/nav-data.tspackages/core/src/services/sandbox/api-reference.ts
apps/docs/src/web/**/*.{ts,tsx}
📄 CodeRabbit inference engine (apps/docs/AGENTS.md)
apps/docs/src/web/**/*.{ts,tsx}: Place React frontend code in thesrc/web/directory, withfrontend.tsxas the entry point andApp.tsxas the main component
Use React 19 for the frontend with support for modern React features and TypeScript
Files:
apps/docs/src/web/components/docs/nav-data.ts
packages/core/src/**/*.ts
📄 CodeRabbit inference engine (packages/core/AGENTS.md)
packages/core/src/**/*.ts: Build TypeScript withbun run buildcommand
Run TypeScript type checking withbun run typecheckcommand
Ensure runtime compatibility with both Browser and Node/Bun environments with no runtime-specific code
Build target must be ESNext with TypeScript declaration files
Prefer interfaces for public APIs
Use generics for reusable type utilities
Ensure no side effects in all exports - all exports must be pure with no global mutations
All relative imports in TypeScript files MUST include the.tsextension
Runbun run buildbefore publishing to compile TypeScript
Files:
packages/core/src/services/sandbox/api-reference.ts
🧠 Learnings (1)
📚 Learning: 2025-12-21T00:31:41.858Z
Learnt from: jhaynie
Repo: agentuity/sdk PR: 274
File: packages/cli/src/cmd/build/vite/server-bundler.ts:12-41
Timestamp: 2025-12-21T00:31:41.858Z
Learning: In Bun runtime, BuildMessage and ResolveMessage are global types and are not exported from the bun module. Do not import { BuildMessage } from 'bun' or similar; these types are available globally and should be used without import. This applies to all TypeScript files that target the Bun runtime within the repository.
Applied to files:
apps/docs/src/web/components/docs/nav-data.tspackages/core/src/services/sandbox/api-reference.ts
🪛 LanguageTool
apps/docs/src/web/content/frontend/static-rendering.mdx
[style] ~57-~57: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ndered HTML into the client template. - If entry-server.tsx is missing, the fron...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
| agentuity project create --name inbound-email-agent | ||
| cd inbound-email-agent | ||
| bun add openai inboundemail | ||
| bun add openai @inboundemail/sdk |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
@inboundemail/sdk npm package Inbound reply isInboundWebhook
💡 Result:
The @inboundemail/sdk is the official TypeScript SDK for the Inbound Email API (v4.4.0 as of Nov 2025), also published as 'inbnd'. It provides a hierarchical interface for managing email sending, receiving, domains, addresses, and webhooks. Install via npm install @inboundemail/sdk or npm install inbnd or npm install inboundemail (related package with identical functionality in examples). Key features relevant to the query: - Inbound webhooks: When emails arrive at configured addresses, Inbound sends POST requests with structured JSON payloads of type InboundWebhookPayload containing the email data. - isInboundWebhook / isInboundWebhookPayload: Type guard function exported by the SDK to validate if a payload is a valid Inbound webhook (e.g., if (!isInboundWebhookPayload(payload)) return bad request). Used in webhook handlers for security and type safety. Often paired with verifyWebhookFromHeaders(request.headers, inbound) for authentication. - Inbound reply: Use inbound.reply(email, { from: '...', text/html: '...', tags: [...] }) to send threaded replies to incoming emails from webhook payloads. Preserves threading via proper headers. Example: await inbound.reply(email, { from: 'support@yourdomain.com', text: 'Thanks for contacting support!', tags: [{ name: 'type', value: 'auto-reply' }] }); Example webhook handler (Next.js App Router): import { Inbound, type InboundWebhookPayload, isInboundWebhookPayload } from 'inboundemail'; // or '@inboundemail/sdk' const inbound = new Inbound(process.env.INBOUND_API_KEY!); export async function POST(request: NextRequest) { const payload: InboundWebhookPayload = await request.json; if (!isInboundWebhookPayload(payload)) { return NextResponse.json({ error: 'Invalid webhook' }, { status: 400 }); } const { email } = payload; // Process email... // Auto-reply await inbound.reply(email, { from: '...', html: '...' }); return NextResponse.json({ success: true }); } Official docs at inbound.new/docs, GitHub repos inboundemail/inbound and inboundemail/sdk (mentioned), npm page.
Citations:
- 1: https://www.npmjs.com/package/@inboundemail/sdk
- 2: https://registry.npmjs.org/%40inboundemail%2Fsdk
- 3: https://github.com/inboundemail/inbound
- 4: https://www.mintlify.com/inboundemail/inbound/guides/receiving-emails
- 5: https://inboundemail-inbound.mintlify.app/guides/receiving-emails
- 6: https://inbound.mintlify.app/api-reference/webhook
- 7: https://inbound.new/email-webhook-api
🏁 Script executed:
cat -n apps/docs/src/web/content/community/inbound-email-agent.mdx | sed -n '50,65p'Repository: agentuity/sdk
Length of output: 540
🏁 Script executed:
cat -n apps/docs/src/web/content/community/inbound-email-agent.mdx | sed -n '165,185p'Repository: agentuity/sdk
Length of output: 789
🏁 Script executed:
cat -n apps/docs/src/web/content/community/inbound-email-agent.mdx | sed -n '180,210p'Repository: agentuity/sdk
Length of output: 1137
🏁 Script executed:
rg "reply\(" apps/docs/src/web/content/community/inbound-email-agent.mdx -A 3 -B 1Repository: agentuity/sdk
Length of output: 397
🏁 Script executed:
cat -n apps/docs/src/web/content/community/inbound-email-agent.mdx | sed -n '207,220p'Repository: agentuity/sdk
Length of output: 468
Fix the @inboundemail/sdk API calls—the example uses undocumented function and method signatures.
The package name @inboundemail/sdk is correct, and Inbound exists as a named export. However, the code uses APIs not documented in the official SDK:
- Line 172: Uses
isInboundWebhook, but the official SDK exportsisInboundWebhookPayloadfor webhook validation. - Lines 207–217: The
reply()method is called with a 3-argument signatureinbound.reply(emailData, {...}, { idempotencyKey })and destructured as{ data, error }, but official documentation only shows a 2-argument signature:inbound.reply(email, { from, subject, text }).
Update both occurrences (lines 172 and 207–217) to match the official SDK API to prevent broken copy-paste examples for readers.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/src/web/content/community/inbound-email-agent.mdx` at line 56, The
example uses incorrect SDK APIs: replace uses of isInboundWebhook with the
official isInboundWebhookPayload for webhook validation, and update the
inbound.reply call to the 2-argument signature described in the SDK (pass the
email object and a single options object with fields like from, subject, text)
and stop destructuring a { data, error } result; instead handle the SDK's actual
return value (e.g., a single response or throw on error) from Inbound.reply.
Update references to the named export Inbound and the methods
isInboundWebhookPayload and reply on the inbound instance so the example matches
the official SDK signatures.
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (1)
apps/docs/src/web/content/services/sandbox/sdk-usage.mdx (1)
199-232: Nit:execution.exitCodeisnumber | undefined, so the failure branch also fires when no exit code is reported.Per
ExecutionSchema(and your own updated table at lines 460-461),exitCodeis optional. The checkif (execution.exitCode !== 0)at line 218 treatsundefinedas failure, which is usually desirable but conflicts with the snippet's framing thatexecute()"waits for the command to finish, then returns stream URLs … when output was captured" (line 201) — readers may reasonably assumeexitCodeis always set post-await. Consider making the example explicit about the undefined case, or checkingexecution.statusinstead.✏️ Suggested tweak
- if (execution.exitCode !== 0) { + if (execution.status !== 'completed' || execution.exitCode !== 0) { ctx.logger.error('Build failed', { + status: execution.status, exitCode: execution.exitCode, stderr, }); }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/sandbox/sdk-usage.mdx` around lines 199 - 232, The example treats execution.exitCode as always present; change the logic to explicitly handle the optional exitCode from sandbox.execute(): when using execution.exitCode, first check typeof execution.exitCode === 'number' and only treat a numeric non-zero value as failure (log exitCode and stderr), otherwise handle the undefined case explicitly (e.g., inspect execution.status or log a warning about missing exit code) so readers see both branches; update references to execution.exitCode and/or switch the failure check to use execution.status (from the ExecutionSchema) if you want a single definitive success/failure check.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/docs/src/web/content/cookbook/integrations/mastra.mdx`:
- Around line 93-104: The fetch calls inside execute (the geocoding fetch and
the weather fetch) parse JSON unconditionally which will throw on 4xx/5xx or
non-JSON responses; before calling GeoResponse.parse or WeatherResponse.parse,
check the Response.status/response.ok for each fetch, handle non-ok responses
(e.g., return a friendly message like `No weather data found for ${location}` or
surface the status and text) and only call .json() when the response is
successful; update the execute function's geocoding and weather fetch blocks to
perform these status checks and graceful returns so GeoResponse.parse and
WeatherResponse.parse never receive invalid data.
In `@apps/docs/src/web/content/cookbook/patterns/chat-with-history.mdx`:
- Line 7: Align the two descriptions of thread state lifetime so they convey the
same semantics: update the introductory sentence that currently says "expires
after 1 hour of inactivity" and the "Key Points" bullet that says "persists for
up to 1 hour" to use one consistent phrase (choose either an idle timeout
wording like "expires after 1 hour of inactivity" or an absolute TTL wording
like "persists for up to 1 hour") and make both occurrences identical; locate
the intro paragraph mentioning thread state and the "Key Points" bullet and
replace the mismatched phrase so both reflect the chosen lifetime wording.
In `@apps/docs/src/web/content/reference/cli/build-configuration.mdx`:
- Around line 55-58: Update the "Reserved Keys" Callout so it no longer marks
the AGENTUITY_PUBLIC_* prefix as internal: remove or change the
`import.meta.env.AGENTUITY_PUBLIC_*` bullet and replace it with a note that only
specific internal keys (e.g., any keys prefixed with an explicit internal marker
like `AGENTUITY_INTERNAL_*` or a short list of concrete internal variable names)
are reserved, while `AGENTUITY_PUBLIC_*` remains available for user-facing
variables (as shown by the example `AGENTUITY_PUBLIC_API_URL`); keep
`process.env.NODE_ENV` listed as reserved and adjust the warning text in the
Callout (the Callout block with title "Reserved Keys") to clearly state which
exact keys are internal versus safe for public use.
In `@apps/docs/src/web/content/services/authentication.mdx`:
- Around line 180-183: The docs text is ambiguous because
createDefaultTrustedOrigins (in packages/auth/src/agentuity/config.ts) adds both
the resolved base URL (from resolveBaseURL) and the raw AGENTUITY_BASE_URL env
var, which can be distinct; update the paragraph and the table row so it
explicitly states that the default trusted origins include the resolved base URL
plus AGENTUITY_BASE_URL (even if resolveBaseURL returned a different value,
e.g., from AGENTUITY_CLOUD_BASE_URL), the incoming request origin,
AGENTUITY_CLOUD_DOMAINS, and AUTH_TRUSTED_DOMAINS, and note that passing
trustedOrigins to createAuth() replaces this list — this clarifies the apparent
duplication between “resolved base URL” and “AGENTUITY_BASE_URL.”
In `@apps/docs/src/web/content/services/observability/sessions-debugging.mdx`:
- Around line 166-179: Add a clear privacy caveat before the indexed metadata
recommendation: state that session/thread metadata (e.g., ctx.session.metadata
and values set from ctx.thread.getMetadata such as userId) are stored
unencrypted/indexed and therefore raw PII (emails, names, tokens, SSNs, etc.)
must not be stored directly; instruct to pseudonymize/hash identifiers or use
non-identifying IDs and show an example suggestion (e.g., hashed or
tenant-scoped ID) instead of raw userId, and apply the same warning to the other
similar instances noted around the example.
- Around line 98-102: The log call uses inline fields instead of a child logger
context; create a child logger from ctx.logger with the searchable fields (e.g.,
sessionId and/or error) and use that child for the error call so fields are part
of logger context. Locate the snippet around the message variable and the
ctx.logger.error call, create a child logger via ctx.logger.child({ sessionId })
(and include error if you want it indexed) and replace ctx.logger.error(...)
with childLogger.error('Request failed', { error: message }) so sessionId is
part of the child context.
---
Nitpick comments:
In `@apps/docs/src/web/content/services/sandbox/sdk-usage.mdx`:
- Around line 199-232: The example treats execution.exitCode as always present;
change the logic to explicitly handle the optional exitCode from
sandbox.execute(): when using execution.exitCode, first check typeof
execution.exitCode === 'number' and only treat a numeric non-zero value as
failure (log exitCode and stderr), otherwise handle the undefined case
explicitly (e.g., inspect execution.status or log a warning about missing exit
code) so readers see both branches; update references to execution.exitCode
and/or switch the failure check to use execution.status (from the
ExecutionSchema) if you want a single definitive success/failure check.
🪄 Autofix (Beta)
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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: b786d4ab-a2ee-4e0b-ba64-74fb2478785f
📒 Files selected for processing (29)
apps/docs/src/web/components/docs/nav-data.tsapps/docs/src/web/content/agents/ai-gateway.mdxapps/docs/src/web/content/cookbook/integrations/mastra.mdxapps/docs/src/web/content/cookbook/patterns/chat-with-history.mdxapps/docs/src/web/content/cookbook/patterns/server-utilities.mdxapps/docs/src/web/content/cookbook/patterns/web-exploration.mdxapps/docs/src/web/content/get-started/project-structure.mdxapps/docs/src/web/content/reference/cli/build-configuration.mdxapps/docs/src/web/content/reference/cli/coder.mdxapps/docs/src/web/content/reference/cli/getting-started.mdxapps/docs/src/web/content/reference/cli/sandbox.mdxapps/docs/src/web/content/reference/cli/storage.mdxapps/docs/src/web/content/reference/migration-guide.mdxapps/docs/src/web/content/reference/sdk-reference/observability.mdxapps/docs/src/web/content/routes/http.mdxapps/docs/src/web/content/services/authentication.mdxapps/docs/src/web/content/services/database/drizzle.mdxapps/docs/src/web/content/services/database/index.mdxapps/docs/src/web/content/services/observability/index.mdxapps/docs/src/web/content/services/observability/logging.mdxapps/docs/src/web/content/services/observability/sessions-debugging.mdxapps/docs/src/web/content/services/observability/tracing.mdxapps/docs/src/web/content/services/observability/web-analytics.mdxapps/docs/src/web/content/services/queues.mdxapps/docs/src/web/content/services/sandbox/index.mdxapps/docs/src/web/content/services/sandbox/sdk-usage.mdxapps/docs/src/web/content/services/storage/key-value.mdxapps/docs/src/web/content/services/storage/object.mdxapps/docs/src/web/content/services/webhooks.mdx
✅ Files skipped from review due to trivial changes (4)
- apps/docs/src/web/components/docs/nav-data.ts
- apps/docs/src/web/content/get-started/project-structure.mdx
- apps/docs/src/web/content/services/observability/logging.mdx
- apps/docs/src/web/content/services/observability/tracing.mdx
🚧 Files skipped from review as they are similar to previous changes (16)
- apps/docs/src/web/content/reference/cli/getting-started.mdx
- apps/docs/src/web/content/services/webhooks.mdx
- apps/docs/src/web/content/agents/ai-gateway.mdx
- apps/docs/src/web/content/routes/http.mdx
- apps/docs/src/web/content/reference/migration-guide.mdx
- apps/docs/src/web/content/services/database/drizzle.mdx
- apps/docs/src/web/content/services/observability/index.mdx
- apps/docs/src/web/content/services/observability/web-analytics.mdx
- apps/docs/src/web/content/services/queues.mdx
- apps/docs/src/web/content/reference/cli/storage.mdx
- apps/docs/src/web/content/services/storage/key-value.mdx
- apps/docs/src/web/content/reference/cli/sandbox.mdx
- apps/docs/src/web/content/services/database/index.mdx
- apps/docs/src/web/content/services/storage/object.mdx
- apps/docs/src/web/content/reference/sdk-reference/observability.mdx
- apps/docs/src/web/content/cookbook/patterns/server-utilities.mdx
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (16)
- GitHub Check: Storage CLI Tests
- GitHub Check: Framework Integration Tests (TanStack & Next.js)
- GitHub Check: Template Integration Tests
- GitHub Check: Standalone Agent Test
- GitHub Check: Queue CLI Tests
- GitHub Check: Sandbox CLI Tests
- GitHub Check: Postgres SSL Integration Test
- GitHub Check: Windows WSL CLI Smoke Test
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Queue SDK Tests
- GitHub Check: Cloud Deployment Tests
- GitHub Check: Package Installation & Usage Test
- GitHub Check: Pack & Upload
- GitHub Check: SDK Integration Test Suite
- GitHub Check: Build
- GitHub Check: Agentuity Deployment
🔇 Additional comments (9)
apps/docs/src/web/content/services/authentication.mdx (2)
133-141: LGTM — accurately describes the default resilient Postgres pool behavior, matchingcreateAuth'screatePostgresDrizzlepath inpackages/auth/src/agentuity/config.ts.
145-168: LGTM — thecreatePostgresDrizzle+drizzleAdapter+requireEnv('DATABASE_URL')example is consistent with the exported API inpackages/drizzle/src/postgres.tsand aligns with the runtime validation pattern used elsewhere in the docs.apps/docs/src/web/content/reference/cli/build-configuration.mdx (2)
22-31: LGTM: the Vite pass-through and React fallback behavior are documented accurately.This matches
packages/cli/src/cmd/build/vite/vite-builder.ts: the CLI writes a React fallback config whenvite.config.tsis missing, then passes that config to Vite via--config.
63-79: LGTM: the envPrefix guidance is consistent across the page.The examples keep
VITE_while adding Agentuity/public prefixes, and the full example mirrors the earlier React plugin plusenvPrefixsetup.Also applies to: 108-123
apps/docs/src/web/content/cookbook/integrations/mastra.mdx (3)
57-60: LGTM — the AI Gateway wording matches the runtime behavior.The callout correctly explains that Agentuity routes through the gateway when no distinct OpenAI key is provided.
126-138: LGTM — the simplified handler output is clearer.Removing token counts from the schema/output and documenting
result.usageas provider-dependent avoids over-promising fields that may not exist.
189-190: LGTM — the structured output typing note is accurate.The comment now points readers to the Zod-derived type from
DayPlanSchema, which is the important distinction in this example.apps/docs/src/web/content/services/sandbox/index.mdx (1)
290-303: Bothsandbox.resume()andagentuity cloud sandbox resumeare confirmed to exist as documented APIs in the official Agentuity documentation. The Resume section is accurate.apps/docs/src/web/content/services/sandbox/sdk-usage.mdx (1)
289-302: No issues found — documentation example is accurate.The
setEnv()API method exists on the public SDK surface with the signaturesetEnv(env: Record<string, string | null>): Promise<Record<string, string>>. The parameter type does acceptnullvalues, and the delete-on-null behavior is explicitly documented: "Pass null to delete a variable." The code example correctly demonstrates this API.
| --- | ||
|
|
||
| Use thread state to maintain conversation history across multiple requests. The thread persists for up to 1 hour, making it ideal for chat sessions. | ||
| Use thread state to keep conversation history across multiple requests. Thread state expires after 1 hour of inactivity, which fits short-lived chat sessions. |
There was a problem hiding this comment.
Inconsistent description of thread state lifetime.
Line 7 now says thread state "expires after 1 hour of inactivity," but the "Key Points" bullet further down (line 190) still says it "persists for up to 1 hour." These describe different semantics (idle timeout vs. absolute TTL). Please align the two to avoid confusing readers.
✏️ Suggested tweak
-- **Thread state** (`ctx.thread.state`) persists for up to 1 hour
++ **Thread state** (`ctx.thread.state`) expires after 1 hour of inactivity🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/src/web/content/cookbook/patterns/chat-with-history.mdx` at line 7,
Align the two descriptions of thread state lifetime so they convey the same
semantics: update the introductory sentence that currently says "expires after 1
hour of inactivity" and the "Key Points" bullet that says "persists for up to 1
hour" to use one consistent phrase (choose either an idle timeout wording like
"expires after 1 hour of inactivity" or an absolute TTL wording like "persists
for up to 1 hour") and make both occurrences identical; locate the intro
paragraph mentioning thread state and the "Key Points" bullet and replace the
mismatched phrase so both reflect the chosen lifetime wording.
- mint signed `chat_user_id` cookies for explorer auth - add `schedule:*` scopes for sandbox demo runs - restore removed docs sections and diagram content - fix stale examples and GitHub App deploy docs
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (3)
apps/docs/src/web/content/get-started/app-configuration.mdx (1)
314-319:⚠️ Potential issue | 🟡 Minor
String(event.data)silently mishandles binary WebSocket frames.If
event.datais aBlob/ArrayBuffer,String(...)coerces to"[object Blob]"/"[object ArrayBuffer]"rather than decoding the payload. Consider guarding withtypeof event.data === 'string'(or decoding binary frames) so readers don't copy a subtle bug.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/get-started/app-configuration.mdx` around lines 314 - 319, The WebSocket message handler uses String(event.data) which corrupts binary frames; update the ws.onMessage callback to detect and properly decode event.data before passing to chatHandler.run — e.g., if typeof event.data === 'string' use it directly, if event.data is an ArrayBuffer use TextDecoder to decode, and if it's a Blob await blob.text() (or convert to ArrayBuffer then decode); ensure the decoded string (not the coerced object) is passed to chatHandler.run({ message: ... }) and keep the ws.send(JSON.stringify(result)) behavior unchanged.apps/docs/src/web/content/cookbook/integrations/mastra.mdx (1)
97-108:⚠️ Potential issue | 🟡 MinorStatus check on
fetchresponses still missing.The past review comment about guarding against non-OK responses from Open-Meteo has not been addressed in this revision. If the geocoding or forecast endpoints return 4xx/5xx (e.g., 429 rate limit) or a non-JSON error body,
await geo.json()/await weather.json()(or the subsequentGeoResponse.parse/WeatherResponse.parse) will throw before the friendly “No weather data found…” fallback is reached, which makes this copy‑paste example fragile for readers.Proposed fix
execute: async ({ location }) => { const geo = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(location)}&count=1`); + if (!geo.ok) { + return `No weather data found for ${location}`; + } const geoData = GeoResponse.parse(await geo.json()); const firstResult = geoData.results?.[0]; if (!firstResult) { return `No weather data found for ${location}`; } const { latitude, longitude } = firstResult; const weather = await fetch(`https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}¤t=temperature_2m`); + if (!weather.ok) { + return `No weather data found for ${location}`; + } const data = WeatherResponse.parse(await weather.json()); return `${location}: ${data.current.temperature_2m}°C`; },🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/integrations/mastra.mdx` around lines 97 - 108, The execute function currently calls fetch for the geocoding and forecast endpoints and immediately awaits geo.json()/weather.json() and passes results to GeoResponse.parse/WeatherResponse.parse, which will throw on non-OK or non-JSON responses; update execute to check response.ok on the geo and weather fetch responses (the geo and weather Response objects) and handle non-OK by returning a friendly message (e.g., "No weather data found for {location}" or include status) before calling .json(); also wrap the .json() and parse calls for GeoResponse.parse and WeatherResponse.parse in try/catch to handle invalid JSON or parse errors and return the same fallback so the example remains robust.apps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdx (1)
295-312:⚠️ Potential issue | 🟠 MajorDoubled-path contradiction in the explicit routing example is still unresolved.
The comment added at line 305 ("Imported routers use paths relative to these mount points") doesn't match the actual
users(lines 42–67) andposts(lines 270–276) routers earlier in the doc, which declare absolute paths (/users,/users/:id,/posts,/posts/:id). Mounting them via.route('/users', users)/.route('/posts', posts)produces/users/users,/users/users/:id,/posts/posts,/posts/posts/:id— the exact issue flagged previously.Either keep the earlier sub-router examples as standalone (no
.route()mounting) and add a separate snippet showing relative-path versions forcreateApp({ router }), or update the existingusers.ts/posts.tssnippets to relative paths and update the standalone-mount narrative accordingly.♻️ Suggested fix — add relative-path variants for the explicit-routing section
Since the earlier
src/api/users.tsandsrc/api/posts.tssnippets are used in the standalone (no-mount) flow withhc<UsersRoute>('/api'), consider showing relative-path versions inline within the "With Explicit Routing" section:## With Explicit Routing If you're mounting relative sub-routers with `createApp({ router })`, export the composed router type: +When mounting via `.route('/users', users)`, the imported router must declare paths relative to the mount point (use `'/'` and `'/:id'`, not `'/users'` and `'/users/:id'`): + +```typescript title="src/api/users.ts (relative variant)" +const router = new Hono<Env>() + .get('/', async (c) => { /* ... */ }) + .get('/:id', async (c) => { /* ... */ }) + .post('/', zValidator('json', CreateUserSchema), async (c) => { /* ... */ }) + .delete('/:id', async (c) => { /* ... */ }); +``` + ```typescript title="src/api/index.ts"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdx` around lines 295 - 312, The explicit-routing example is contradictory because the shown users and posts routers declare absolute paths but are then mounted with .route('/users', users) / .route('/posts', posts), resulting in doubled paths; fix by either (A) converting the exported routers (symbols: users, posts) to use relative routes (e.g., get('/', get('/:id', post('/', delete('/:id'))) so mounting with router.route('/users', users) produces /users and /users/:id), or (B) keep the existing absolute-path users/posts routers and change the example/preamble around createApp({ router }) / export type AppRoute = typeof router to show them used standalone (no .route mounting) and remove the misleading comment about "paths relative to these mount points"; update the comment text and the example accordingly so router, users, posts, createApp and AppRoute are consistent.
🧹 Nitpick comments (2)
apps/docs/src/web/content/get-started/app-configuration.mdx (1)
17-25: Inconsistent key order indeployment.resourcesexamples.The first example lists
memory,cpu,disk(lines 20–22) while the second example at lines 183–187 listscpu,memory,disk. Aligning the order across both snippets makes the docs easier to scan and reduces the impression that order is meaningful.📝 Proposed alignment
"deployment": { "resources": { - "memory": "500Mi", "cpu": "500m", + "memory": "500Mi", "disk": "500Mi" }, "domains": [] }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/get-started/app-configuration.mdx` around lines 17 - 25, Examples for deployment.resources are inconsistent: one snippet shows keys in order memory, cpu, disk while another shows cpu, memory, disk. Pick a canonical order (recommended: memory, cpu, disk) and update the other snippet so both examples use the same key order under deployment.resources; specifically adjust the snippet that defines deployment.resources (the one listing cpu, memory, disk) to reorder keys to memory, cpu, disk so both examples match.apps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdx (1)
35-40: Update to Zod v4 top-levelz.email()API.In Zod v4+,
z.string().email()is deprecated in favor of the top-levelz.email()schema. The chained method still works at runtime but emits deprecation warnings. Update to use the new preferred style:♻️ Proposed update
const CreateUserSchema = z.object({ name: z.string().min(1), - email: z.string().email(), + email: z.email(), });🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdx` around lines 35 - 40, Replace the chained deprecated z.string().email() with the Zod v4 top-level z.email() in the CreateUserSchema definition: keep name as z.string().min(1) but change the email property to z.email() so CreateUserSchema uses z.object({ name: z.string().min(1), email: z.email() }); update any other similar usages in this file that reference the chained .email() to the top-level z.email() API.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/docs/src/middleware/auth.ts`:
- Around line 6-16: The isSecureRequest function treats forwardedProto strictly
equal to 'https', which fails when x-forwarded-proto contains a comma-separated
chain; change the check in isSecureRequest to split forwardedProto on commas,
take the leftmost entry, trim and lowercase it, and compare that value to
'https' (fall back to the existing new URL(url).protocol check in the catch path
if forwardedProto is undefined or empty); ensure you normalize casing and
whitespace so values like "HTTPS, http" are correctly recognized as secure.
In `@apps/docs/src/web/content/cookbook/integrations/nextjs.mdx`:
- Around line 147-152: The current example uses new URL('/api',
agentuityBaseUrl) which, because the path starts with a leading slash, will
discard any path suffix on agentuityBaseUrl (e.g., https://api.example.com/v1
becomes https://api.example.com/api); update the docs around the
agentuityBaseUrl and client creation to call out this behavior and recommend the
safer alternative for backends mounted on sub-paths: construct the URL with a
relative segment (e.g., use 'api' not '/api') and ensure agentuityBaseUrl has a
trailing slash (mention a helper like ensureTrailingSlash) before passing it to
new URL, and include a short explanatory sentence about why agentuityBaseUrl vs
new URL('/api', ...) matters for sub-path deployments referencing the
agentuityBaseUrl and client constants.
---
Duplicate comments:
In `@apps/docs/src/web/content/cookbook/integrations/mastra.mdx`:
- Around line 97-108: The execute function currently calls fetch for the
geocoding and forecast endpoints and immediately awaits
geo.json()/weather.json() and passes results to
GeoResponse.parse/WeatherResponse.parse, which will throw on non-OK or non-JSON
responses; update execute to check response.ok on the geo and weather fetch
responses (the geo and weather Response objects) and handle non-OK by returning
a friendly message (e.g., "No weather data found for {location}" or include
status) before calling .json(); also wrap the .json() and parse calls for
GeoResponse.parse and WeatherResponse.parse in try/catch to handle invalid JSON
or parse errors and return the same fallback so the example remains robust.
In `@apps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdx`:
- Around line 295-312: The explicit-routing example is contradictory because the
shown users and posts routers declare absolute paths but are then mounted with
.route('/users', users) / .route('/posts', posts), resulting in doubled paths;
fix by either (A) converting the exported routers (symbols: users, posts) to use
relative routes (e.g., get('/', get('/:id', post('/', delete('/:id'))) so
mounting with router.route('/users', users) produces /users and /users/:id), or
(B) keep the existing absolute-path users/posts routers and change the
example/preamble around createApp({ router }) / export type AppRoute = typeof
router to show them used standalone (no .route mounting) and remove the
misleading comment about "paths relative to these mount points"; update the
comment text and the example accordingly so router, users, posts, createApp and
AppRoute are consistent.
In `@apps/docs/src/web/content/get-started/app-configuration.mdx`:
- Around line 314-319: The WebSocket message handler uses String(event.data)
which corrupts binary frames; update the ws.onMessage callback to detect and
properly decode event.data before passing to chatHandler.run — e.g., if typeof
event.data === 'string' use it directly, if event.data is an ArrayBuffer use
TextDecoder to decode, and if it's a Blob await blob.text() (or convert to
ArrayBuffer then decode); ensure the decoded string (not the coerced object) is
passed to chatHandler.run({ message: ... }) and keep the
ws.send(JSON.stringify(result)) behavior unchanged.
---
Nitpick comments:
In `@apps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdx`:
- Around line 35-40: Replace the chained deprecated z.string().email() with the
Zod v4 top-level z.email() in the CreateUserSchema definition: keep name as
z.string().min(1) but change the email property to z.email() so CreateUserSchema
uses z.object({ name: z.string().min(1), email: z.email() }); update any other
similar usages in this file that reference the chained .email() to the top-level
z.email() API.
In `@apps/docs/src/web/content/get-started/app-configuration.mdx`:
- Around line 17-25: Examples for deployment.resources are inconsistent: one
snippet shows keys in order memory, cpu, disk while another shows cpu, memory,
disk. Pick a canonical order (recommended: memory, cpu, disk) and update the
other snippet so both examples use the same key order under
deployment.resources; specifically adjust the snippet that defines
deployment.resources (the one listing cpu, memory, disk) to reorder keys to
memory, cpu, disk so both examples match.
🪄 Autofix (Beta)
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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 9d2bbdd8-9799-4af5-8ea2-9d7a99e3efa0
📒 Files selected for processing (13)
apps/docs/src/api/sandbox/route.tsapps/docs/src/middleware/auth.tsapps/docs/src/web/content/cookbook/integrations/mastra.mdxapps/docs/src/web/content/cookbook/integrations/nextjs.mdxapps/docs/src/web/content/cookbook/integrations/openai-agents.mdxapps/docs/src/web/content/cookbook/integrations/tanstack-start.mdxapps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdxapps/docs/src/web/content/get-started/app-configuration.mdxapps/docs/src/web/content/reference/api/sandboxes.mdxapps/docs/src/web/content/reference/cli/deployment.mdxapps/docs/src/web/content/reference/cli/opencode-plugin.mdxapps/docs/src/web/content/reference/sdk-reference/events.mdxapps/docs/src/web/content/services/observability/web-analytics.mdx
✅ Files skipped from review due to trivial changes (3)
- apps/docs/src/api/sandbox/route.ts
- apps/docs/src/web/content/reference/api/sandboxes.mdx
- apps/docs/src/web/content/services/observability/web-analytics.mdx
🚧 Files skipped from review as they are similar to previous changes (4)
- apps/docs/src/web/content/cookbook/integrations/tanstack-start.mdx
- apps/docs/src/web/content/reference/sdk-reference/events.mdx
- apps/docs/src/web/content/reference/cli/deployment.mdx
- apps/docs/src/web/content/reference/cli/opencode-plugin.mdx
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (16)
- GitHub Check: Sandbox CLI Tests
- GitHub Check: Queue CLI Tests
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Windows WSL CLI Smoke Test
- GitHub Check: Storage CLI Tests
- GitHub Check: Framework Integration Tests (TanStack & Next.js)
- GitHub Check: Queue SDK Tests
- GitHub Check: Standalone Agent Test
- GitHub Check: Package Installation & Usage Test
- GitHub Check: Template Integration Tests
- GitHub Check: SDK Integration Test Suite
- GitHub Check: Cloud Deployment Tests
- GitHub Check: Postgres SSL Integration Test
- GitHub Check: Pack & Upload
- GitHub Check: Build
- GitHub Check: Agentuity Deployment
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use Biome as code formatter with tabs (width 3), single quotes, semicolons, lineWidth 100, and trailingCommas es5
Files:
apps/docs/src/middleware/auth.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx}: Use TypeScript Strict mode with ESNext target and bundler moduleResolution
UseStructuredErrorfrom@agentuity/corefor error handling
Files:
apps/docs/src/middleware/auth.ts
🧠 Learnings (1)
📚 Learning: 2025-12-21T00:31:41.858Z
Learnt from: jhaynie
Repo: agentuity/sdk PR: 274
File: packages/cli/src/cmd/build/vite/server-bundler.ts:12-41
Timestamp: 2025-12-21T00:31:41.858Z
Learning: In Bun runtime, BuildMessage and ResolveMessage are global types and are not exported from the bun module. Do not import { BuildMessage } from 'bun' or similar; these types are available globally and should be used without import. This applies to all TypeScript files that target the Bun runtime within the repository.
Applied to files:
apps/docs/src/middleware/auth.ts
🔇 Additional comments (6)
apps/docs/src/web/content/cookbook/integrations/nextjs.mdx (2)
33-35: LGTM!The shortened comment is clear and conveys the same intent.
122-124: LGTM — clarification reads well.The revised callout cleanly conveys that
AgentuityProvideris opt-in and only relevant when@agentuity/reactis already in play.apps/docs/src/web/content/cookbook/integrations/openai-agents.mdx (2)
72-74: Callout still lacks a concretetracingDisabledexample.The revised callout names three ways to disable tracing but only the env-var form is self-contained; readers can't tell where
tracingDisabled: truegoes (Runner constructor vs. per-runrunConfig). A short snippet such asnew Runner({ tracingDisabled: true })(or notingrun(agent, input, { runConfig: { tracingDisabled: true } })for per-run) would make this copy-pasteable and remove ambiguity.
85-85: Module-scoperefundEscalationsstill grows unbounded across requests.This swap from
console.logto a top-levelconst refundEscalations: string[] = []will accumulate escalation reasons in worker memory across unrelated invocations/users for the lifetime of the process — a memory leak and a potential privacy issue when sharing reasons across sessions. Consider scoping it inside the handler / viaRunContext, persisting through Agentuity's KV/storage, or at least adding an inline comment that this array is illustrative and not production-safe.Also applies to: 115-121
apps/docs/src/web/content/cookbook/integrations/mastra.mdx (1)
23-23: No action required —openai/gpt-5.4is a valid, currently published OpenAI model.The model identifier is correct.
openai/gpt-5.4is a legitimate OpenAI frontier model released in March 2026 with a 1.05M context window, explicitly supported by Mastra with documented pricing ($3/$15 per 1M input/output tokens). The.4suffix is part of OpenAI's actual naming scheme for this model.> Likely an incorrect or invalid review comment.apps/docs/src/middleware/auth.ts (1)
23-43: Signed-cookie migration looks correct.Properly distinguishes
false(tampered signature → warn + reissue) fromundefined(absent), and the new cookie attributes (httpOnly, dynamicsecure,sameSite: 'Lax',path: '/', 1ymaxAge) are sensible defaults for an anonymous identifier. Logging only on issuance (not per-request) keeps log volume reasonable.
- Match auth handling to proxy header behavior - Make cookbook examples safer to adapt - Align sandbox port docs with CLI behavior - Clarify session and trace ID correlation
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
apps/docs/src/web/content/cookbook/patterns/server-utilities.mdx (1)
376-389:⚠️ Potential issue | 🟠 MajorHandle schema validation failures explicitly.
SessionPatchSchema.parse(...)will throw on bad input, which turns a client error into a 500. Return a 400 instead of letting invalid JSON reach the persistence call.🛠️ Suggested fix
router.post('/:id', async (c) => { const sessionId = c.req.param('id'); - const body: SessionPatch = SessionPatchSchema.parse(await c.req.json()); + const payload = await c.req.json(); + const parsed = SessionPatchSchema.safeParse(payload); + if (!parsed.success) { + return c.json({ error: 'Invalid session payload' }, 400); + } + const body: SessionPatch = parsed.data; const existing = await c.var.kv.get<ChatSession>('sessions', sessionId);🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/patterns/server-utilities.mdx` around lines 376 - 389, The handler registered in router.post (the async (c) => { ... }) currently calls SessionPatchSchema.parse(...) which will throw on invalid input and produce a 500; wrap the parse in a try/catch (catching the validation error, e.g., ZodError or generic Error) to return a 400 response for client-side validation failures instead of proceeding to persistence (c.var.kv.set) — if validation fails, respond with c.json({ error: 'Invalid session payload', details: ... }, 400) or similar and do not call c.var.kv.set('sessions', sessionId, ...); otherwise continue with the existing session merge and set logic and logging (c.var.logger.info).apps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdx (1)
80-109:⚠️ Potential issue | 🟡 MinorNarrow the client-import warning to value imports.
The current warning overstates the risk: TypeScript erases
import typeandexport typeat compile time, and the docs app'stsconfig.jsonenforces this withverbatimModuleSyntax: true. The actual concern is value imports from server route files. Rewrite to clarify:Suggested wording
-<Callout type="warning" title="Never Import Server Route Files from Client Code"> -Even `import type` can cause bundlers to trace the module graph and pull server-only code into the client bundle. -</Callout> +<Callout type="warning" title="Never Value-Import Server Route Files from Client Code"> +Use the type-only barrel shown below for client code, and keep any runtime imports out of server route modules. +</Callout>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdx` around lines 80 - 109, Update the warning Callout to say "Never import value exports from server route files" and adjust the explanatory text to clarify that TypeScript-only imports/exports (e.g., import type / export type) are erased at compile time (and tsconfig option verbatimModuleSyntax: true prevents bundlers from treating them as values), while value imports will pull server code into the client bundle; keep the guidance to use a dedicated type-only barrel (referenced as src/shared/api-types.ts) and show importing via import type in the frontend example (src/web/api.ts) so readers know to prefer type-only re-exports and avoid runtime/value imports from server modules like src/api/users.ts.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/docs/src/middleware/auth.ts`:
- Around line 31-40: The middleware currently logs the generated per-user cookie
value via c.var.logger.info('Issued chat_user_id cookie', { userId }), which
records a stable user identifier; remove the userId from the log (or replace it
with a non-identifying request ID) so the log entry does not contain the cookie
value. Locate the block where userId is assigned and setSignedCookie is called
(look for userId, setSignedCookie, and the logger call 'Issued chat_user_id
cookie') and change the logger invocation to either log only a generic message
or include a non-identifying token (e.g., requestId) instead of userId.
- Around line 6-16: The middleware's isSecureRequest function currently trusts
the x-forwarded-proto header (forwardedProto) to decide cookie Secure flag,
which is unsafe unless that header is stripped/overwritten by a trusted edge
proxy; update the code to either require a trusted proxy check before using
forwardedProto or fall back to direct connection properties: add verification
against a configured trusted proxy list (e.g., compare req.socket.remoteAddress
/ request IP to allowed proxies) or an environment flag (e.g., TRUSTED_PROXY)
and only use forwardedProto when the request originates from a trusted proxy;
modify isSecureRequest (and the middleware code that sets Secure on cookies) to
consult that trust check first and default to using new URL(url).protocol or
req.secure when not trusted.
In `@apps/docs/src/web/content/cookbook/integrations/nextjs.mdx`:
- Around line 147-163: The docs currently use new URL() on
NEXT_PUBLIC_AGENTUITY_BASE_URL (agentuityBaseUrl) without stating it must be a
fully qualified absolute URL, which causes runtime Invalid URL errors for bare
hosts or relative paths; update the text around the examples (the
agentuityBaseUrl/baseUrl explanation and the hc<ApiRouter> examples) to
explicitly state that NEXT_PUBLIC_AGENTUITY_BASE_URL must be a fully qualified
absolute URL (including scheme like https://) and add a brief note or validation
guidance showing that new URL(...) will throw for invalid inputs and how to
provide a correct value.
In `@apps/docs/src/web/content/cookbook/patterns/server-utilities.mdx`:
- Around line 535-543: The copy mentions Zod but the example uses only
`@agentuity/schema`; update the wording around the schema-conversion example to
reference Agentuity schemas (or both Agentuity and Zod if intended) so it
matches the snippet — adjust the descriptive sentence that currently references
"Convert Agentuity or Zod schemas" to accurately reflect the example using s
from `@agentuity/schema` and the toJSONSchema function, or add a parallel Zod
example if you want to keep Zod mentioned; ensure references to s and
toJSONSchema remain consistent with the code shown.
---
Outside diff comments:
In `@apps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdx`:
- Around line 80-109: Update the warning Callout to say "Never import value
exports from server route files" and adjust the explanatory text to clarify that
TypeScript-only imports/exports (e.g., import type / export type) are erased at
compile time (and tsconfig option verbatimModuleSyntax: true prevents bundlers
from treating them as values), while value imports will pull server code into
the client bundle; keep the guidance to use a dedicated type-only barrel
(referenced as src/shared/api-types.ts) and show importing via import type in
the frontend example (src/web/api.ts) so readers know to prefer type-only
re-exports and avoid runtime/value imports from server modules like
src/api/users.ts.
In `@apps/docs/src/web/content/cookbook/patterns/server-utilities.mdx`:
- Around line 376-389: The handler registered in router.post (the async (c) => {
... }) currently calls SessionPatchSchema.parse(...) which will throw on invalid
input and produce a 500; wrap the parse in a try/catch (catching the validation
error, e.g., ZodError or generic Error) to return a 400 response for client-side
validation failures instead of proceeding to persistence (c.var.kv.set) — if
validation fails, respond with c.json({ error: 'Invalid session payload',
details: ... }, 400) or similar and do not call c.var.kv.set('sessions',
sessionId, ...); otherwise continue with the existing session merge and set
logic and logging (c.var.logger.info).
🪄 Autofix (Beta)
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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8e8daee2-c5f9-49a9-ac7d-cccf2e26dba8
📒 Files selected for processing (20)
apps/docs/src/middleware/auth.tsapps/docs/src/web/components/docs/nav-data.tsapps/docs/src/web/content/cookbook/integrations/chat-sdk.mdxapps/docs/src/web/content/cookbook/integrations/mastra.mdxapps/docs/src/web/content/cookbook/integrations/nextjs.mdxapps/docs/src/web/content/cookbook/integrations/openai-agents.mdxapps/docs/src/web/content/cookbook/patterns/chat-with-history.mdxapps/docs/src/web/content/cookbook/patterns/hono-rpc-tanstack-query.mdxapps/docs/src/web/content/cookbook/patterns/product-search.mdxapps/docs/src/web/content/cookbook/patterns/server-utilities.mdxapps/docs/src/web/content/get-started/app-configuration.mdxapps/docs/src/web/content/get-started/installation.mdxapps/docs/src/web/content/reference/cli/build-configuration.mdxapps/docs/src/web/content/reference/cli/sandbox.mdxapps/docs/src/web/content/services/authentication.mdxapps/docs/src/web/content/services/coder.mdxapps/docs/src/web/content/services/observability/index.mdxapps/docs/src/web/content/services/observability/sessions-debugging.mdxapps/docs/src/web/content/services/sandbox/sdk-usage.mdxapps/docs/src/web/content/services/storage/custom.mdx
✅ Files skipped from review due to trivial changes (2)
- apps/docs/src/web/components/docs/nav-data.ts
- apps/docs/src/web/content/reference/cli/build-configuration.mdx
🚧 Files skipped from review as they are similar to previous changes (14)
- apps/docs/src/web/content/get-started/installation.mdx
- apps/docs/src/web/content/cookbook/integrations/openai-agents.mdx
- apps/docs/src/web/content/services/authentication.mdx
- apps/docs/src/web/content/cookbook/integrations/chat-sdk.mdx
- apps/docs/src/web/content/cookbook/integrations/mastra.mdx
- apps/docs/src/web/content/services/coder.mdx
- apps/docs/src/web/content/get-started/app-configuration.mdx
- apps/docs/src/web/content/services/observability/index.mdx
- apps/docs/src/web/content/reference/cli/sandbox.mdx
- apps/docs/src/web/content/cookbook/patterns/product-search.mdx
- apps/docs/src/web/content/cookbook/patterns/chat-with-history.mdx
- apps/docs/src/web/content/services/sandbox/sdk-usage.mdx
- apps/docs/src/web/content/services/observability/sessions-debugging.mdx
- apps/docs/src/web/content/services/storage/custom.mdx
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (16)
- GitHub Check: Framework Integration Tests (TanStack & Next.js)
- GitHub Check: Queue SDK Tests
- GitHub Check: Queue CLI Tests
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Storage CLI Tests
- GitHub Check: Sandbox CLI Tests
- GitHub Check: Template Integration Tests
- GitHub Check: Package Installation & Usage Test
- GitHub Check: Cloud Deployment Tests
- GitHub Check: SDK Integration Test Suite
- GitHub Check: Standalone Agent Test
- GitHub Check: Postgres SSL Integration Test
- GitHub Check: Build
- GitHub Check: Windows WSL CLI Smoke Test
- GitHub Check: Pack & Upload
- GitHub Check: Agentuity Deployment
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use Biome as code formatter with tabs (width 3), single quotes, semicolons, lineWidth 100, and trailingCommas es5
Files:
apps/docs/src/middleware/auth.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx}: Use TypeScript Strict mode with ESNext target and bundler moduleResolution
UseStructuredErrorfrom@agentuity/corefor error handling
Files:
apps/docs/src/middleware/auth.ts
🧠 Learnings (1)
📚 Learning: 2025-12-21T00:31:41.858Z
Learnt from: jhaynie
Repo: agentuity/sdk PR: 274
File: packages/cli/src/cmd/build/vite/server-bundler.ts:12-41
Timestamp: 2025-12-21T00:31:41.858Z
Learning: In Bun runtime, BuildMessage and ResolveMessage are global types and are not exported from the bun module. Do not import { BuildMessage } from 'bun' or similar; these types are available globally and should be used without import. This applies to all TypeScript files that target the Bun runtime within the repository.
Applied to files:
apps/docs/src/middleware/auth.ts
🔇 Additional comments (3)
apps/docs/src/web/content/cookbook/integrations/nextjs.mdx (2)
33-35: Looks good.The comment reflow is harmless and improves readability.
122-124: Good clarification.This correctly removes the suggestion that plain
hc()usage requiresAgentuityProvider.apps/docs/src/web/content/cookbook/patterns/server-utilities.mdx (1)
74-93: Good fail-fast setup.Validating
AGENTUITY_SDK_KEYandAGENTUITY_REGIONbefore building the adapter keeps this example from failing later in the request path.
- Protect `chat_user_id` from logs and untrusted proxy headers - Validate webhook, session, and agent examples before writes - Clarify `AGENTUITY_SDK_KEY` versus CLI auth usage - Align sandbox, analytics, and Coder docs with runtime behavior
- Clarify when to use `Runner` tracing config - Align observability with `OLAP Warehouse`
1 participant
Summary by CodeRabbit
New Features
batchUpdate,batchClose)Bug Fixes
Documentation