Conversation
- Add cookbook pages to sync with examples repo - Add brand SVGs and organize images by section - Add CLI reference for `oauth` and `monitoring` - Add explicit routing docs for `createApp` - Fix task aliases, sandbox events, broken links
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds many new documentation pages and corresponding route modules and generated route-tree entries; expands navigation data; updates docs layout behavior (hash-aware scrolling), TOC/Tabs logic, and code-block overscroll styles; removes the CSS ellipsis loading animation; and introduces broad content updates across services, cookbook, routes, and CLI references. Changes
🚥 Pre-merge checks | ✅ 1✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
📦 Canary Packages Publishedversion: PackagesInstallAdd to your {
"dependencies": {
"@agentuity/email": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-email-1.0.56-88332dc.tgz",
"@agentuity/opencode": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-opencode-1.0.56-88332dc.tgz",
"@agentuity/claude-code": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-claude-code-1.0.56-88332dc.tgz",
"@agentuity/runtime": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-runtime-1.0.56-88332dc.tgz",
"@agentuity/webhook": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-webhook-1.0.56-88332dc.tgz",
"@agentuity/keyvalue": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-keyvalue-1.0.56-88332dc.tgz",
"@agentuity/vector": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-vector-1.0.56-88332dc.tgz",
"@agentuity/cli": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-cli-1.0.56-88332dc.tgz",
"@agentuity/evals": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-evals-1.0.56-88332dc.tgz",
"@agentuity/react": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-react-1.0.56-88332dc.tgz",
"@agentuity/workbench": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-workbench-1.0.56-88332dc.tgz",
"@agentuity/task": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-task-1.0.56-88332dc.tgz",
"@agentuity/sandbox": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-sandbox-1.0.56-88332dc.tgz",
"@agentuity/drizzle": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-drizzle-1.0.56-88332dc.tgz",
"@agentuity/db": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-db-1.0.56-88332dc.tgz",
"@agentuity/postgres": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-postgres-1.0.56-88332dc.tgz",
"@agentuity/schema": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-schema-1.0.56-88332dc.tgz",
"@agentuity/auth": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-auth-1.0.56-88332dc.tgz",
"@agentuity/frontend": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-frontend-1.0.56-88332dc.tgz",
"@agentuity/queue": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-queue-1.0.56-88332dc.tgz",
"@agentuity/core": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-core-1.0.56-88332dc.tgz",
"@agentuity/server": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-server-1.0.56-88332dc.tgz",
"@agentuity/coder": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-coder-1.0.56-88332dc.tgz",
"@agentuity/schedule": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-schedule-1.0.56-88332dc.tgz"
}
}Or install directly: bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-email-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-opencode-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-claude-code-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-runtime-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-webhook-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-keyvalue-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-vector-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-cli-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-evals-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-react-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-workbench-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-task-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-sandbox-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-drizzle-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-db-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-postgres-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-schema-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-auth-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-frontend-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-queue-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-core-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-server-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-coder-1.0.56-88332dc.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.56-88332dc/agentuity-schedule-1.0.56-88332dc.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: 11
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (8)
apps/docs/src/web/content/reference/api/sandboxes.mdx (1)
1160-1214:⚠️ Potential issue | 🟡 MinorMissing
autoResumedfield in Response Fields.The prose at lines 1160 and 1164 describes the
autoResumedbehavior, but this field is not documented in the Response Fields table. According to the schema inpackages/core/src/services/sandbox/execute.ts(lines 47-57),autoResumedis a top-level boolean field on successful responses.Suggested addition to Response Fields
{ "name": "outputTruncated", "type": "boolean", "description": "Whether the captured output was truncated due to size limits", "required": false + }, + { + "name": "autoResumed", + "type": "boolean", + "description": "True if the sandbox was automatically resumed from a suspended state before execution", + "required": false } ]} />🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/api/sandboxes.mdx` around lines 1160 - 1214, The documentation omits the top-level boolean field autoResumed described in the prose and produced by the sandbox execution logic; update the ResponseFields declaration in the sandboxes.mdx API doc to include an entry for "autoResumed" (type: boolean, description: "True if the sandbox was automatically resumed before execution", required: false) so it matches the schema in packages/core/src/services/sandbox/execute.ts and the surrounding prose; locate the ResponseFields component block in sandboxes.mdx and add the autoResumed field alongside executionId, status, exitCode, etc.apps/docs/src/web/content/agents/standalone-execution.mdx (4)
126-136: 🛠️ Refactor suggestion | 🟠 MajorAdd imports to make this example copy-pasteable.
This standalone code example is missing import statements. As per coding guidelines, standalone examples should include imports to ensure they are runnable.
📦 Add missing imports
+import { createAgentContext } from '@agentuity/runtime'; +import analyzeAgent from '@agent/analyze'; +import respondAgent from '@agent/respond'; + const ctx = createAgentContext(); const result = await ctx.invoke(async () => {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/agents/standalone-execution.mdx` around lines 126 - 136, The example is missing required imports so it isn't copy-pasteable; add import statements for the symbols used (e.g., createAgentContext, analyzeAgent, respondAgent, and any types like userInput) at the top of the snippet so the block can run as-is—specifically import/create the createAgentContext function, the analyzeAgent and respondAgent modules (or instances) and any utility/types referenced, then keep the existing usage of ctx.invoke, analyzeAgent.run, and respondAgent.run unchanged.
89-97: 🛠️ Refactor suggestion | 🟠 MajorAdd imports to make this example copy-pasteable.
This standalone code example is missing import statements. As per coding guidelines, standalone examples should include imports to ensure they are runnable.
📦 Add missing imports
+import { createAgentContext } from '@agentuity/runtime'; +import messageAgent from '@agent/message'; + const ctx = createAgentContext({ trigger: 'websocket' }); // Each run gets its own session and tracing span🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/agents/standalone-execution.mdx` around lines 89 - 97, The example is missing required imports, so make the snippet copy-pasteable by adding import statements for createAgentContext, messageAgent, and any websocket type/constructor used; specifically import createAgentContext and messageAgent from their library/module and add an import or declaration for websocket (e.g., WebSocket or a server-side websocket instance) so the symbols used in the snippet (createAgentContext, messageAgent, ctx.run, websocket) are defined and the example compiles/runs.
109-120: 🛠️ Refactor suggestion | 🟠 MajorAdd import to make this example copy-pasteable.
This standalone code example is missing the import statement. As per coding guidelines, standalone examples should include imports at the top.
📦 Add missing import
+import { createAgentContext } from '@agentuity/runtime'; + const ctx = createAgentContext({ trigger: 'cron' }); await ctx.invoke(async () => {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/agents/standalone-execution.mdx` around lines 109 - 120, The example is missing the import needed to make it copy-pasteable; add the appropriate import for createAgentContext at the top of the snippet so the sample can run as-is (e.g., import { createAgentContext } from '...'), ensuring the import aligns with how createAgentContext is exported in the codebase; keep the rest of the example using ctx.invoke, ctx.kv.get, ctx.stream.create and ctx.logger.info unchanged.
70-81: 🛠️ Refactor suggestion | 🟠 MajorAdd imports to make this example copy-pasteable.
This standalone code example is missing import statements. As per coding guidelines, standalone examples should include imports at the top to ensure they are copy-pasteable and runnable.
📦 Add missing imports
+import { createAgentContext } from '@agentuity/runtime'; +import analyzeAgent from '@agent/analyze'; +import respondAgent from '@agent/respond'; + const ctx = createAgentContext(); // First agent analyzes the input🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/agents/standalone-execution.mdx` around lines 70 - 81, The example is missing import statements; add top-of-file imports so the snippet is copy-pasteable — specifically import createAgentContext and any AgentContext types, and import the agent symbols analyzeAgent and respondAgent (and any helper like userInput or its source) used in the snippet; ensure the imports reference the modules where those symbols are defined so the calls to createAgentContext(), ctx.run(analyzeAgent, …) and ctx.run(respondAgent, …) resolve.apps/docs/src/web/content/agents/evaluations.mdx (2)
257-257:⚠️ Potential issue | 🟡 MinorUpdate "App" to "Web App" for branding consistency.
Line 257 still references "App" while line 26 was updated to "Web App". For consistency with the PR's branding updates, this should also say "Web App".
📝 Proposed fix for consistency
-When you need scores visible in your UI (not just the App), run LLM-as-judge inline in your handler and include the results in your output schema: +When you need scores visible in your UI (not just the Web App), run LLM-as-judge inline in your handler and include the results in your output schema:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/agents/evaluations.mdx` at line 257, Update the phrasing on the sentence that starts "When you need scores visible in your UI (not just the App), run LLM-as-judge inline in your handler and include the results in your output schema:" to replace "App" with "Web App" so it matches the earlier change; locate the exact sentence containing "not just the App" and change it to "not just the Web App".
54-54:⚠️ Potential issue | 🔴 CriticalUpdate OpenAI model names to current versions.
The code examples use
gpt-5-nanoandgpt-5-mini, but the current valid OpenAI models as of March 2026 aregpt-5.4-nanoandgpt-5.4-mini. Update all occurrences throughout the file (lines 54, 119, 169, 214, 282, 288, 327, 437) to use the correct model identifiers with the.4version specifier. Users copying these examples will receive API errors with the current model names.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/agents/evaluations.mdx` at line 54, Replace all deprecated OpenAI model identifiers 'gpt-5-nano' and 'gpt-5-mini' with the current names 'gpt-5.4-nano' and 'gpt-5.4-mini' respectively; specifically update occurrences that look like model: openai('gpt-5-nano') and model: openai('gpt-5-mini') so examples use openai('gpt-5.4-nano') and openai('gpt-5.4-mini') to avoid API errors.apps/docs/src/web/content/get-started/quickstart.mdx (1)
201-205:⚠️ Potential issue | 🟡 MinorKeep the rename consistent in this section.
Line 201 switches to “Web App,” but the adjacent callout still says “App.” Updating both at once avoids mixed terminology in the same onboarding step.
🤖 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/quickstart.mdx` around lines 201 - 205, The section mixes the terms "Web App" and "App"; update the Callout component and any text inside it (the Callout title "What You'll See in the App" and the bullet "App populates with" if present) to use "Web App" consistently so both the sentence "View deployments, logs, and more in the [Web App]" and the Callout (Callout title and content) use the same term; search for the strings "What You'll See in the App" and "App populates with" and replace "App" with "Web App" (or otherwise make the wording consistent) in the Callout block.
🧹 Nitpick comments (15)
apps/docs/src/web/content/reference/cli/development.mdx (1)
248-248: Consider making the link text more context-specific.The link text "details" is generic. Consider describing what the reader will find, e.g., "loading order" or "env file precedence," to help readers decide whether to follow the link.
📝 Suggested improvement
-| **Environment** | `.env`, `.env.development` ([details](/get-started/app-configuration#environment-specific-files)) | Cloud variables (via `cloud env`) | +| **Environment** | `.env`, `.env.development` ([loading order](/get-started/app-configuration#environment-specific-files)) | Cloud variables (via `cloud env`) |As per coding guidelines: "Make cross-links context-specific: include why the reader would follow the link."
🤖 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/development.mdx` at line 248, Replace the generic link text "details" in the table row that shows Environment (.env, .env.development) with a context-specific phrase that describes what the link covers (for example "env file precedence" or "loading order"), so update the markdown cell containing | **Environment** | `.env`, `.env.development` ([details](/get-started/app-configuration#environment-specific-files)) | to use the chosen descriptive text (e.g., ([env file precedence](/get-started/app-configuration#environment-specific-files))) to make the cross-link self-explanatory.apps/docs/src/web/components/docs/toc.tsx (1)
67-79: Deeper heading levels lose visual hierarchy in the TOCNow that all heading depths are rendered, only indenting
depth === 3(Line 78) makesh4+appear flat relative to higher levels. Add progressive depth-based indentation so deeper sections remain scannable.💡 Proposed tweak
className={cn( 'block transition-colors hover:text-cyan-500', - depth === 3 && 'pl-3', + depth === 3 && 'pl-3', + depth === 4 && 'pl-6', + depth >= 5 && 'pl-9', activeId === id ? 'text-cyan-600 dark:text-cyan-400 font-medium' : 'text-zinc-600 dark:text-zinc-400' )}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/components/docs/toc.tsx` around lines 67 - 79, The TOC currently only indents depth === 3, causing h4+ to lose hierarchy; update the mapping in the flatHeadings render (where you build the <a> with className via cn, inside the map that uses flatHeadings, id, value, depth and calls scrollToHeading) to compute a depth-based padding class instead of a single depth === 3 check — e.g., derive an indentation class from the heading depth (map depths to progressive 'pl-...' classes or compute one from (depth) and include that string in the cn call) so deeper headings (depth >= 3) receive increasing left padding while preserving existing activeId styling and behavior.apps/docs/src/web/content/services/storage/object.mdx (2)
44-55: Add an explicit “do not commit.env” warning next to credential keys.Since this section lists raw credential variable names, adding a one-line secret-handling warning would reduce accidental leakage risk.
🔐 Suggested addition
The credentials written to `.env`: - `S3_ACCESS_KEY_ID` - `S3_SECRET_ACCESS_KEY` - `S3_BUCKET` - `S3_ENDPOINT` + +<Callout type="warning" title="Treat Credentials as Secrets"> +Never commit `.env` to version control or expose these values in client-side code. +</Callout>As per coding guidelines, "Use 'warning' for gotchas and required setup".
🤖 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 44 - 55, Add an explicit one-line “do not commit .env” warning next to the listed credential keys (S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET, S3_ENDPOINT) inside the existing Callout (Callout type="warning" title="Dev Mode Credentials") so readers are clearly instructed not to check `.env` into version control; update the Callout content to include a concise secret-handling sentence (e.g., "Do not commit your `.env` file or share these credentials.") and keep the rest of the instructions about running `agentuity project add storage` and `agentuity cloud env pull` unchanged.
30-42: Clarify bucket creation vs project-linking behavior to avoid ambiguity.The current wording can be read as “create” being sufficient; a tiny wording tweak can make “linking” explicitly required.
✏️ Suggested wording tweak
-`agentuity project add storage` links the bucket and writes credentials to `.env`. `agentuity cloud storage create` also writes credentials if run from a project directory. +`agentuity project add storage` links the bucket to the current project and writes credentials to `.env`. +`agentuity cloud storage create` can also write credentials when run from a project directory, but run `agentuity project add storage` to guarantee the bucket is linked to this project.🤖 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 30 - 42, Reword the steps to clearly state that creating a bucket and linking it to the project are separate required steps: explicitly say that running `agentuity cloud storage create` creates the bucket (and will write credentials only if run from inside a project directory), while `agentuity project add storage` is required to link the existing bucket to your project and will write credentials to `.env`; update the copy around the two commands to remove ambiguity and make "linking" explicitly required.apps/docs/src/web/content/services/sandbox/index.mdx (1)
205-213: Code example missingclientinitialization.The example imports
sandboxEventListbutclientis used without showing how to create or obtain anAPIClientinstance. The callout mentions it's required, but readers cannot copy-paste and run this example.Consider adding a brief note or showing client creation:
import { sandboxEventList, createAPIClient } from '@agentuity/server'; const client = createAPIClient({ apiKey: process.env.AGENTUITY_API_KEY });As per coding guidelines: "Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable".
🤖 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/index.mdx` around lines 205 - 213, The example calls sandboxEventList(client, ...) but never shows how to obtain the API client; update the snippet to import and instantiate the client (e.g., import createAPIClient or APIClient from '@agentuity/server' and create a client instance using createAPIClient({ apiKey: process.env.AGENTUITY_API_KEY }) or equivalent) so that sandboxEventList has a valid client variable; ensure the import list includes sandboxEventList and the client factory and that the example shows creating the client before calling sandboxEventList.apps/docs/src/web/components/docs/docs-layout.tsx (1)
86-92: Remove stalebiome-ignoreon the effect dependencies.At Line 87, the suppression is no longer needed since dependencies are explicitly listed (
location.pathname,location.hash). Keeping it can mask future real dependency drift.Diff suggestion
- // biome-ignore lint/correctness/useExhaustiveDependencies: location.pathname is used as a trigger to scroll to top on route change React.useLayoutEffect(() => { if (!location.hash) { mainRef.current?.scrollTo(0, 0); } }, [location.pathname, location.hash]);🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/components/docs/docs-layout.tsx` around lines 86 - 92, The comment points out an unnecessary suppression: remove the stale "biome-ignore lint/correctness/useExhaustiveDependencies" comment above the React.useLayoutEffect since you already list the correct dependencies (location.pathname, location.hash); update the docs-layout.tsx by deleting that biome-ignore line so the effect reads simply as React.useLayoutEffect(() => { if (!location.hash) mainRef.current?.scrollTo(0, 0); }, [location.pathname, location.hash]) and leave the useLayoutEffect, mainRef, and dependency array intact.apps/docs/src/web/content/agents/standalone-execution.mdx (1)
36-42: Explicitly mark which options are optional.The options table doesn't clearly indicate which parameters are required versus optional. As per coding guidelines, readers should not need to parse type signatures to determine optionality.
📝 Clarify parameter optionality
Consider adding "(optional)" to the description column for each optional parameter, or add an "Required" column to the table. For example:
| Option | Type | Description | |--------|------|-------------| -| `sessionId` | `string` | Custom session ID. Auto-generated from trace context if not provided | +| `sessionId` | `string` | (optional) Custom session ID. Auto-generated from trace context if not provided |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/agents/standalone-execution.mdx` around lines 36 - 42, Update the options table so each parameter clearly shows whether it's required or optional: mark sessionId, trigger, thread, session, and parentContext as "(optional)" in their Description cells (or add a "Required" column and set them to "No"), and ensure the descriptions for sessionId explain auto-generation from trace context and for trigger list allowed values. Target the table rows for the symbols `sessionId`, `trigger`, `thread`, `session`, and `parentContext` in standalone-execution.mdx.apps/docs/src/web/content/reference/github-app.mdx (1)
110-119: Make thepredeploysample generic, or label it monorepo-only.Line 113’s
cd ../.. && bun run build:packagesis repo-specific and reads like required setup in a general reference page. A smaller sample keeps the focus on the actual contract: definingpredeployreplaces the automatic install step.
As per coding guidelines, "Strip boilerplate from code examples; show only the feature being demonstrated."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/reference/github-app.mdx` around lines 110 - 119, The example in package.json uses a repo-specific predeploy command (the `predeploy` script runs `cd ../.. && bun install && bun run build:packages`) which confuses a general reference; change the `predeploy` sample to a generic placeholder or explicitly mark it as monorepo-only. Update the `predeploy` entry in the shown package.json to either a generic command like `"predeploy": "your-predeploy-command-here"` or add a short comment/label next to `predeploy` indicating “(monorepo-only)” so readers understand it’s not required for all projects, keeping the `deploy` script example (`"deploy": "agentuity deploy"`) unchanged.apps/docs/src/web/content/routes/explicit-routing.mdx (1)
198-198: Optional style refinement.Consider "provide access to" instead of "give you access" for slightly more formal documentation tone.
-Both `createRouter()` and `new Hono<Env>()` give you access to Agentuity context variables in your route handlers: +Both `createRouter()` and `new Hono<Env>()` provide access to Agentuity context variables in your route handlers:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/routes/explicit-routing.mdx` at line 198, The phrasing "give you access to" in the sentence containing createRouter() and new Hono<Env>() is informal; update it to "provide access to" for a more formal tone by replacing "give you access to Agentuity context variables in your route handlers" with "provide access to Agentuity context variables in your route handlers" where the sentence references createRouter() and new Hono<Env>().apps/docs/src/web/components/docs/nav-data.ts (1)
483-487: Align this nav title with the page/crumb name for consistency.On Line 484,
Hono RPCappears shortened versus the page/route labeling used elsewhere (Hono RPC + TanStack Query). Keeping one canonical title improves nav/search consistency.♻️ Suggested tweak
- title: 'Hono RPC', + title: 'Hono RPC + TanStack Query',🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/components/docs/nav-data.ts` around lines 483 - 487, Update the nav entry object whose title is currently 'Hono RPC' (the entry with url '/cookbook/patterns/hono-rpc-tanstack-query' in nav-data.ts) to use the canonical page/crumb title 'Hono RPC + TanStack Query' so the navigation label matches the page and breadcrumb naming for consistency.apps/docs/src/web/content/services/schedules.mdx (1)
205-215: Use inline API references (or full runnable snippets) for the two short examples.On Line 205 and Line 212, the fenced snippets depend on
ctx/inputbut aren’t runnable examples. Prefer inline code for these method-shape callouts, or expand them to full examples with imports and handler context.As per coding guidelines, "Use inline code references to show API shape, config values, or method signatures without imports; use standalone examples for concepts that require copy-pasteable code" and "Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/schedules.mdx` around lines 205 - 215, The snippets use ctx/input but aren’t runnable; replace the two fenced examples with either inline code references (e.g., use inline backtick references like `ctx.schedule.getDestination(scheduleId, destinationId)` and `ctx.schedule.getDelivery(scheduleId, deliveryId, params?)`) or expand them into full standalone examples that include imports and a handler/context setup and show passing `params` through to `getDelivery` (which calls `listDeliveries`) so callers can control pagination; update the example referencing `getDelivery` to demonstrate passing `params` (e.g., `{ page: X, pageSize: Y }`) and mention `listDeliveries` behavior, and ensure the runnable snippet includes the necessary imports and `ctx`/`input` construction.apps/docs/src/web/content/reference/cli/oauth.mdx (2)
8-10: Use a warning callout for the requiredcloudprefix.This is mandatory command syntax rather than background context, so
warningwill make the gotcha stand out before readers copy the commands.As per coding guidelines, "Use 'info' callout type for context and clarifications, 'warning' for gotchas and required setup, 'tip' for optimizations and advanced patterns."
🤖 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/oauth.mdx` around lines 8 - 10, Change the Callout type from "info" to "warning" for the Cloud Prefix note so the required `cloud` prefix is shown as a mandatory/gotcha message; locate the Callout block (Callout type="info" title="Cloud Prefix Required") in oauth.mdx and update the type attribute to "warning" while keeping the title and content text unchanged.
24-42: Spell out whichoidc createflags are optional.The table reads as a flat list right now, so readers have to infer the non-interactive required set from the example. Mark the optional flags explicitly and call out the required set in prose.
As per coding guidelines, "Explicitly mark optional parameters as 'optional' in prose; readers should not need to parse type signatures."
🤖 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/oauth.mdx` around lines 24 - 42, The options table for the "agentuity cloud oidc create" command doesn't indicate which flags are optional; update the docs to explicitly mark optional flags and state the required set in prose: add a short paragraph above or below the table that lists the required non-interactive flags (e.g., the minimum flags needed for non-interactive creation) and prefix optional flags in the table with "(optional)" or similar wording for `--description`, `--homepage-url`, `--redirect-uris`, `--scopes`, and `--json`, while keeping `--name` and `--type` identified as required if that is the case for `oidc create` usage. Ensure you reference the command name "agentuity cloud oidc create" and the flag names (`--name`, `--description`, `--homepage-url`, `--type`, `--redirect-uris`, `--scopes`, `--json`) so readers can easily see which are optional.apps/docs/src/web/content/services/webhooks.mdx (1)
34-41: Repeat theAPIClientsetup in the standalone SDK snippets.
clientis only created inSetup, but the later fences are presented as isolated examples. Inline the setup into each fence or label those snippets as continuations so each section is runnable when copied.As per coding guidelines, "Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable."
Also applies to: 76-88, 92-103, 109-120, 140-160, 167-179, 187-199, 215-225
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/webhooks.mdx` around lines 34 - 41, The code examples reuse the APIClient instantiation only in the initial "Setup" fence so later standalone fences are not copy-paste runnable; update each isolated code fence that uses client/APIClient (including the blocks referenced at 76-88, 92-103, 109-120, 140-160, 167-179, 187-199, 215-225) to include the minimal setup lines: the imports for APIClient and createLogger, creation of logger via createLogger(), and instantiation of client = new APIClient(process.env.AGENTUITY_API_URL!, logger), or alternatively mark those fences as "continued from Setup" if you intend them to be non-standalone; search for usages of APIClient, client, and createLogger in the file to locate each fence to modify.apps/docs/src/web/content/cookbook/integrations/mastra.mdx (1)
68-115: Merge the splitindex.tsexamples or add the missing symbols.The second
src/agent/weather/index.tsandsrc/agent/day-planner/index.tsfences referenceweatherAgentandplannerAgentwithout declaring them, so they are not copy-pasteable as shown.As per coding guidelines, "Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable."
Also applies to: 127-178
🤖 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 68 - 115, The two code fences split the Agent creation and the Agentuity handler, leaving referenced symbols (weatherAgent, plannerAgent) undefined; either merge the examples into a single file per agent or add the missing imports/exports so the handler can reference the agent instance. Specifically, ensure the file that contains the handler imports the agent instance (e.g., import { weatherAgent } from './agent' or export the Agent instance when creating it with createTool/Agent), and do the same for plannerAgent; update the handler examples (createAgent usage) to import the matching agent instance and any types used (createAgent, s) so each fenced example is self-contained and copy-paste runnable.
🤖 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/langchain.mdx`:
- Around line 102-130: The snippet is not runnable because it references
undeclared symbols (search, calculate, getTime, message, langchainAgent,
messages) and omits required setup for
createLangChainAgent/ChatOpenAI/HumanMessage; to fix, make the example
self-contained by either (A) inlining minimal stub implementations and imports
for the tools (variables search, calculate, getTime), defining a sample message
variable and messages array, and showing agent creation with
createLangChainAgent/ChatOpenAI/HumanMessage so the stream example can run, or
(B) explicitly mark the code block as a continuation/partial and add a brief
comment header referencing where the omitted setup lives; apply the same change
to the second block (lines 138-158) so both examples are copy-pasteable.
- Around line 49-54: The code examples set ChatOpenAI model to 'gpt-4.1' (e.g.
in the createLangChainAgent call where ChatOpenAI is instantiated); update every
ChatOpenAI instantiation to use 'gpt-5.4' instead of 'gpt-4.1' (there are three
occurrences), ensuring instances like new ChatOpenAI({ model: 'gpt-4.1', ... })
become new ChatOpenAI({ model: 'gpt-5.4', ... }) so all examples consistently
use the current flagship model.
In `@apps/docs/src/web/content/cookbook/integrations/mastra.mdx`:
- Around line 74-86: The snippet for weatherTool has execute always calling
hardcoded coordinates while echoing the caller's location, causing mislabeled
results; update weatherTool (inputSchema and execute) to either accept latitude
and longitude (e.g., add lat and lon to inputSchema and use them in the fetch
URL) or perform a geocoding lookup inside execute using the provided location
string to resolve coordinates before calling the open-meteo API, and ensure the
returned string uses the actual coordinates/data (from
data.current.temperature_2m) and the input location consistently.
In `@apps/docs/src/web/content/cookbook/integrations/openai-agents.mdx`:
- Around line 80-125: This snippet is missing tool definitions and uses
console.log; define or import minimal tool stubs for lookupInvoice and
processRefund (e.g., simple objects/functions named lookupInvoice and
processRefund used in billingAgent and refundAgent), and replace the console.log
in the handoff onHandoff handler with the Agentuity logger (use the ctx
parameter and call ctx.logger.info or ctx.logger.debug) so the
EscalationData-driven handoff is runnable; update the handoff call
(handoff(refundAgent, { onHandoff: (ctx, input) => ctx.logger.info(`Refund
escalation: ${input?.reason}`), inputType: EscalationData, toolNameOverride:
'escalate_to_refund' })) and ensure these edits are made alongside the
triageAgent/Agent.create usage so the file is copy-paste runnable.
In `@apps/docs/src/web/content/get-started/app-configuration.mdx`:
- Around line 224-259: The docs currently show a "File loading order" for
`agentuity dev` but omit where `.env.local` fits; update the "File loading
order" section to explicitly include `.env.local` and its precedence (e.g., list
the full order such that later files override earlier ones, e.g., `.env` →
`.env.development` → `.env.local` or whatever the actual precedence is) and add
a short clarifying sentence after the table stating whether `.env.local`
overrides `.env.development` during `agentuity dev`; ensure the terms
`.env.local`, `.env.development`, `agentuity dev`, and the "File loading order"
header are updated so readers can unambiguously determine precedence.
In `@apps/docs/src/web/content/reference/cli/deployment.mdx`:
- Line 254: Replace the repeated external link in the sentence "Or toggle it in
the [Web App](https://app.agentuity.com) under your project's **Settings >
GitHub > Preview Environments**." with plain text by removing the Markdown link
and leaving "Web App" unlinked (e.g., "Or toggle it in the Web App under your
project's **Settings > GitHub > Preview Environments**."), ensuring the first
instance of https://app.agentuity.com on the page remains the only external
link.
- Around line 263-265: Change the Callout node for the GitHub prerequisite from
type="info" to type="warning" so the required setup is correctly emphasized;
keep the title "GitHub Connection Required" and preserve the inner content and
links ([Agentuity GitHub App], [Setting Up Git Integration]) but update the
Callout attribute from info to warning in the Callout declaration.
In `@apps/docs/src/web/content/routes/webrtc.mdx`:
- Line 21: The documentation registers the signaling route with
router.get('/signal', webrtc()) but client examples connect to
'/api/call/signal', causing a mismatch and 404s; either make the route path in
the server code match the client examples (e.g., change router.get('/signal',
...) to router.get('/call/signal', webrtc())) or update all client examples to
use the documented '/signal' endpoint (search for occurrences of
'/api/call/signal' in the file and make them consistent), and if a nested router
or prefix is intended, add a brief note explaining the '/call' prefix and where
it is applied so readers understand the routing context.
- Around line 169-224: The examples call the useWebRTCCall hook and related
functions (sendString, sendStringTo, sendJSON, sendBinary, closeDataChannel,
startScreenShare, stopScreenShare) at module scope and reference undeclared
variables (roomId, peerId, remotePeerId, signalUrl), which violates React Rules
of Hooks and makes snippets non-runnable; fix by wrapping each snippet inside a
React function component or custom hook (e.g., show a parent component that
declares/receives roomId, peerId, signalUrl as props or state) or add a clear
note that the examples must be used inside a component with those variables
provided, and update the examples to reference those declared names so
useWebRTCCall is only called inside a component/custom hook.
In `@apps/docs/src/web/content/services/queues.mdx`:
- Around line 44-79: The docs example and types are out of sync with the actual
queue API: replace the current call signature
ctx.queue.createQueue('notifications', { queueType: ... }) and the camelCase
QueueCreateResult with the canonical single-request object shape used by the
service (use ctx.queue.createQueue({ name: 'notifications', queue_type:
'worker', description: 'Order notifications', settings: { default_ttl_seconds,
default_visibility_timeout_seconds, default_max_retries,
max_in_flight_per_client, retention_seconds }}) and update the returned result
shape to match the service (snake_case fields), ensure the "Queue Settings"
section uses the same snake_case keys, and remove or revise the "Idempotent
Creation" claim unless you can reference the service implementation
(ctx.queue.createQueue) to confirm idempotency; if it is idempotent, add a short
source-backed note referencing the function/method that enforces it.
In `@apps/docs/src/web/content/services/tasks.mdx`:
- Around line 256-273: The code calls ctx.task.confirmAttachment(attachment.id)
unconditionally after uploading to presigned_url; change the flow so you only
call ctx.task.confirmAttachment when the PUT succeeds: after await
fetch(presigned_url, { method: 'PUT', ... }) inspect the response (e.g. if
(!response.ok) { log the status/error and return or throw } ), and only then
call ctx.task.confirmAttachment(attachment.id). Also surface the fetch error
details in the log/exception so callers can retry or mark the attachment failed
instead of leaving a broken record.
---
Outside diff comments:
In `@apps/docs/src/web/content/agents/evaluations.mdx`:
- Line 257: Update the phrasing on the sentence that starts "When you need
scores visible in your UI (not just the App), run LLM-as-judge inline in your
handler and include the results in your output schema:" to replace "App" with
"Web App" so it matches the earlier change; locate the exact sentence containing
"not just the App" and change it to "not just the Web App".
- Line 54: Replace all deprecated OpenAI model identifiers 'gpt-5-nano' and
'gpt-5-mini' with the current names 'gpt-5.4-nano' and 'gpt-5.4-mini'
respectively; specifically update occurrences that look like model:
openai('gpt-5-nano') and model: openai('gpt-5-mini') so examples use
openai('gpt-5.4-nano') and openai('gpt-5.4-mini') to avoid API errors.
In `@apps/docs/src/web/content/agents/standalone-execution.mdx`:
- Around line 126-136: The example is missing required imports so it isn't
copy-pasteable; add import statements for the symbols used (e.g.,
createAgentContext, analyzeAgent, respondAgent, and any types like userInput) at
the top of the snippet so the block can run as-is—specifically import/create the
createAgentContext function, the analyzeAgent and respondAgent modules (or
instances) and any utility/types referenced, then keep the existing usage of
ctx.invoke, analyzeAgent.run, and respondAgent.run unchanged.
- Around line 89-97: The example is missing required imports, so make the
snippet copy-pasteable by adding import statements for createAgentContext,
messageAgent, and any websocket type/constructor used; specifically import
createAgentContext and messageAgent from their library/module and add an import
or declaration for websocket (e.g., WebSocket or a server-side websocket
instance) so the symbols used in the snippet (createAgentContext, messageAgent,
ctx.run, websocket) are defined and the example compiles/runs.
- Around line 109-120: The example is missing the import needed to make it
copy-pasteable; add the appropriate import for createAgentContext at the top of
the snippet so the sample can run as-is (e.g., import { createAgentContext }
from '...'), ensuring the import aligns with how createAgentContext is exported
in the codebase; keep the rest of the example using ctx.invoke, ctx.kv.get,
ctx.stream.create and ctx.logger.info unchanged.
- Around line 70-81: The example is missing import statements; add top-of-file
imports so the snippet is copy-pasteable — specifically import
createAgentContext and any AgentContext types, and import the agent symbols
analyzeAgent and respondAgent (and any helper like userInput or its source) used
in the snippet; ensure the imports reference the modules where those symbols are
defined so the calls to createAgentContext(), ctx.run(analyzeAgent, …) and
ctx.run(respondAgent, …) resolve.
In `@apps/docs/src/web/content/get-started/quickstart.mdx`:
- Around line 201-205: The section mixes the terms "Web App" and "App"; update
the Callout component and any text inside it (the Callout title "What You'll See
in the App" and the bullet "App populates with" if present) to use "Web App"
consistently so both the sentence "View deployments, logs, and more in the [Web
App]" and the Callout (Callout title and content) use the same term; search for
the strings "What You'll See in the App" and "App populates with" and replace
"App" with "Web App" (or otherwise make the wording consistent) in the Callout
block.
In `@apps/docs/src/web/content/reference/api/sandboxes.mdx`:
- Around line 1160-1214: The documentation omits the top-level boolean field
autoResumed described in the prose and produced by the sandbox execution logic;
update the ResponseFields declaration in the sandboxes.mdx API doc to include an
entry for "autoResumed" (type: boolean, description: "True if the sandbox was
automatically resumed before execution", required: false) so it matches the
schema in packages/core/src/services/sandbox/execute.ts and the surrounding
prose; locate the ResponseFields component block in sandboxes.mdx and add the
autoResumed field alongside executionId, status, exitCode, etc.
---
Nitpick comments:
In `@apps/docs/src/web/components/docs/docs-layout.tsx`:
- Around line 86-92: The comment points out an unnecessary suppression: remove
the stale "biome-ignore lint/correctness/useExhaustiveDependencies" comment
above the React.useLayoutEffect since you already list the correct dependencies
(location.pathname, location.hash); update the docs-layout.tsx by deleting that
biome-ignore line so the effect reads simply as React.useLayoutEffect(() => { if
(!location.hash) mainRef.current?.scrollTo(0, 0); }, [location.pathname,
location.hash]) and leave the useLayoutEffect, mainRef, and dependency array
intact.
In `@apps/docs/src/web/components/docs/nav-data.ts`:
- Around line 483-487: Update the nav entry object whose title is currently
'Hono RPC' (the entry with url '/cookbook/patterns/hono-rpc-tanstack-query' in
nav-data.ts) to use the canonical page/crumb title 'Hono RPC + TanStack Query'
so the navigation label matches the page and breadcrumb naming for consistency.
In `@apps/docs/src/web/components/docs/toc.tsx`:
- Around line 67-79: The TOC currently only indents depth === 3, causing h4+ to
lose hierarchy; update the mapping in the flatHeadings render (where you build
the <a> with className via cn, inside the map that uses flatHeadings, id, value,
depth and calls scrollToHeading) to compute a depth-based padding class instead
of a single depth === 3 check — e.g., derive an indentation class from the
heading depth (map depths to progressive 'pl-...' classes or compute one from
(depth) and include that string in the cn call) so deeper headings (depth >= 3)
receive increasing left padding while preserving existing activeId styling and
behavior.
In `@apps/docs/src/web/content/agents/standalone-execution.mdx`:
- Around line 36-42: Update the options table so each parameter clearly shows
whether it's required or optional: mark sessionId, trigger, thread, session, and
parentContext as "(optional)" in their Description cells (or add a "Required"
column and set them to "No"), and ensure the descriptions for sessionId explain
auto-generation from trace context and for trigger list allowed values. Target
the table rows for the symbols `sessionId`, `trigger`, `thread`, `session`, and
`parentContext` in standalone-execution.mdx.
In `@apps/docs/src/web/content/cookbook/integrations/mastra.mdx`:
- Around line 68-115: The two code fences split the Agent creation and the
Agentuity handler, leaving referenced symbols (weatherAgent, plannerAgent)
undefined; either merge the examples into a single file per agent or add the
missing imports/exports so the handler can reference the agent instance.
Specifically, ensure the file that contains the handler imports the agent
instance (e.g., import { weatherAgent } from './agent' or export the Agent
instance when creating it with createTool/Agent), and do the same for
plannerAgent; update the handler examples (createAgent usage) to import the
matching agent instance and any types used (createAgent, s) so each fenced
example is self-contained and copy-paste runnable.
In `@apps/docs/src/web/content/reference/cli/development.mdx`:
- Line 248: Replace the generic link text "details" in the table row that shows
Environment (.env, .env.development) with a context-specific phrase that
describes what the link covers (for example "env file precedence" or "loading
order"), so update the markdown cell containing | **Environment** | `.env`,
`.env.development`
([details](/get-started/app-configuration#environment-specific-files)) | to use
the chosen descriptive text (e.g., ([env file
precedence](/get-started/app-configuration#environment-specific-files))) to make
the cross-link self-explanatory.
In `@apps/docs/src/web/content/reference/cli/oauth.mdx`:
- Around line 8-10: Change the Callout type from "info" to "warning" for the
Cloud Prefix note so the required `cloud` prefix is shown as a mandatory/gotcha
message; locate the Callout block (Callout type="info" title="Cloud Prefix
Required") in oauth.mdx and update the type attribute to "warning" while keeping
the title and content text unchanged.
- Around line 24-42: The options table for the "agentuity cloud oidc create"
command doesn't indicate which flags are optional; update the docs to explicitly
mark optional flags and state the required set in prose: add a short paragraph
above or below the table that lists the required non-interactive flags (e.g.,
the minimum flags needed for non-interactive creation) and prefix optional flags
in the table with "(optional)" or similar wording for `--description`,
`--homepage-url`, `--redirect-uris`, `--scopes`, and `--json`, while keeping
`--name` and `--type` identified as required if that is the case for `oidc
create` usage. Ensure you reference the command name "agentuity cloud oidc
create" and the flag names (`--name`, `--description`, `--homepage-url`,
`--type`, `--redirect-uris`, `--scopes`, `--json`) so readers can easily see
which are optional.
In `@apps/docs/src/web/content/reference/github-app.mdx`:
- Around line 110-119: The example in package.json uses a repo-specific
predeploy command (the `predeploy` script runs `cd ../.. && bun install && bun
run build:packages`) which confuses a general reference; change the `predeploy`
sample to a generic placeholder or explicitly mark it as monorepo-only. Update
the `predeploy` entry in the shown package.json to either a generic command like
`"predeploy": "your-predeploy-command-here"` or add a short comment/label next
to `predeploy` indicating “(monorepo-only)” so readers understand it’s not
required for all projects, keeping the `deploy` script example (`"deploy":
"agentuity deploy"`) unchanged.
In `@apps/docs/src/web/content/routes/explicit-routing.mdx`:
- Line 198: The phrasing "give you access to" in the sentence containing
createRouter() and new Hono<Env>() is informal; update it to "provide access to"
for a more formal tone by replacing "give you access to Agentuity context
variables in your route handlers" with "provide access to Agentuity context
variables in your route handlers" where the sentence references createRouter()
and new Hono<Env>().
In `@apps/docs/src/web/content/services/sandbox/index.mdx`:
- Around line 205-213: The example calls sandboxEventList(client, ...) but never
shows how to obtain the API client; update the snippet to import and instantiate
the client (e.g., import createAPIClient or APIClient from '@agentuity/server'
and create a client instance using createAPIClient({ apiKey:
process.env.AGENTUITY_API_KEY }) or equivalent) so that sandboxEventList has a
valid client variable; ensure the import list includes sandboxEventList and the
client factory and that the example shows creating the client before calling
sandboxEventList.
In `@apps/docs/src/web/content/services/schedules.mdx`:
- Around line 205-215: The snippets use ctx/input but aren’t runnable; replace
the two fenced examples with either inline code references (e.g., use inline
backtick references like `ctx.schedule.getDestination(scheduleId,
destinationId)` and `ctx.schedule.getDelivery(scheduleId, deliveryId, params?)`)
or expand them into full standalone examples that include imports and a
handler/context setup and show passing `params` through to `getDelivery` (which
calls `listDeliveries`) so callers can control pagination; update the example
referencing `getDelivery` to demonstrate passing `params` (e.g., `{ page: X,
pageSize: Y }`) and mention `listDeliveries` behavior, and ensure the runnable
snippet includes the necessary imports and `ctx`/`input` construction.
In `@apps/docs/src/web/content/services/storage/object.mdx`:
- Around line 44-55: Add an explicit one-line “do not commit .env” warning next
to the listed credential keys (S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY,
S3_BUCKET, S3_ENDPOINT) inside the existing Callout (Callout type="warning"
title="Dev Mode Credentials") so readers are clearly instructed not to check
`.env` into version control; update the Callout content to include a concise
secret-handling sentence (e.g., "Do not commit your `.env` file or share these
credentials.") and keep the rest of the instructions about running `agentuity
project add storage` and `agentuity cloud env pull` unchanged.
- Around line 30-42: Reword the steps to clearly state that creating a bucket
and linking it to the project are separate required steps: explicitly say that
running `agentuity cloud storage create` creates the bucket (and will write
credentials only if run from inside a project directory), while `agentuity
project add storage` is required to link the existing bucket to your project and
will write credentials to `.env`; update the copy around the two commands to
remove ambiguity and make "linking" explicitly required.
In `@apps/docs/src/web/content/services/webhooks.mdx`:
- Around line 34-41: The code examples reuse the APIClient instantiation only in
the initial "Setup" fence so later standalone fences are not copy-paste
runnable; update each isolated code fence that uses client/APIClient (including
the blocks referenced at 76-88, 92-103, 109-120, 140-160, 167-179, 187-199,
215-225) to include the minimal setup lines: the imports for APIClient and
createLogger, creation of logger via createLogger(), and instantiation of client
= new APIClient(process.env.AGENTUITY_API_URL!, logger), or alternatively mark
those fences as "continued from Setup" if you intend them to be non-standalone;
search for usages of APIClient, client, and createLogger in the file to locate
each fence to modify.
🪄 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: ecd1ad5c-a2db-45ce-af9f-1eda8b8632dc
⛔ Files ignored due to path filters (8)
apps/docs/src/generated/env.d.tsis excluded by!**/generated/**apps/docs/src/web/public/images/community/inbound-logo.svgis excluded by!**/*.svgapps/docs/src/web/public/images/community/snow-leopard-favicon.pngis excluded by!**/*.pngapps/docs/src/web/public/images/integrations/langchain.svgis excluded by!**/*.svgapps/docs/src/web/public/images/integrations/mastra.svgis excluded by!**/*.svgapps/docs/src/web/public/images/integrations/nextjs.svgis excluded by!**/*.svgapps/docs/src/web/public/images/integrations/openai.svgis excluded by!**/*.svgapps/docs/src/web/public/images/integrations/tanstack.svgis excluded by!**/*.svg
📒 Files selected for processing (62)
apps/docs/src/web/app.cssapps/docs/src/web/components/docs/docs-layout.tsxapps/docs/src/web/components/docs/mdx-components.tsxapps/docs/src/web/components/docs/nav-data.tsapps/docs/src/web/components/docs/tabs.tsxapps/docs/src/web/components/docs/toc.tsxapps/docs/src/web/content/agents/evaluations.mdxapps/docs/src/web/content/agents/standalone-execution.mdxapps/docs/src/web/content/community/index.mdxapps/docs/src/web/content/cookbook/index.mdxapps/docs/src/web/content/cookbook/integrations/langchain.mdxapps/docs/src/web/content/cookbook/integrations/mastra.mdxapps/docs/src/web/content/cookbook/integrations/meta.jsonapps/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/get-started/app-configuration.mdxapps/docs/src/web/content/get-started/quickstart.mdxapps/docs/src/web/content/get-started/what-is-agentuity.mdxapps/docs/src/web/content/reference/api/sandboxes.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/meta.jsonapps/docs/src/web/content/reference/cli/monitoring.mdxapps/docs/src/web/content/reference/cli/oauth.mdxapps/docs/src/web/content/reference/cli/sandbox.mdxapps/docs/src/web/content/reference/github-app.mdxapps/docs/src/web/content/reference/meta.jsonapps/docs/src/web/content/reference/migration-guide.mdxapps/docs/src/web/content/reference/sdk-reference.mdxapps/docs/src/web/content/routes/explicit-routing.mdxapps/docs/src/web/content/routes/http.mdxapps/docs/src/web/content/routes/index.mdxapps/docs/src/web/content/routes/webrtc.mdxapps/docs/src/web/content/services/email.mdxapps/docs/src/web/content/services/index.mdxapps/docs/src/web/content/services/queues.mdxapps/docs/src/web/content/services/sandbox/index.mdxapps/docs/src/web/content/services/sandbox/snapshots.mdxapps/docs/src/web/content/services/schedules.mdxapps/docs/src/web/content/services/storage/object.mdxapps/docs/src/web/content/services/tasks.mdxapps/docs/src/web/content/services/webhooks.mdxapps/docs/src/web/index.cssapps/docs/src/web/routeTree.gen.tsapps/docs/src/web/routes/_docs/cookbook/integrations/langchain.tsxapps/docs/src/web/routes/_docs/cookbook/integrations/mastra.tsxapps/docs/src/web/routes/_docs/cookbook/integrations/nextjs.tsxapps/docs/src/web/routes/_docs/cookbook/integrations/openai-agents.tsxapps/docs/src/web/routes/_docs/cookbook/integrations/tanstack-start.tsxapps/docs/src/web/routes/_docs/cookbook/patterns/hono-rpc-tanstack-query.tsxapps/docs/src/web/routes/_docs/reference/cli/monitoring.tsxapps/docs/src/web/routes/_docs/reference/cli/oauth.tsxapps/docs/src/web/routes/_docs/reference/github-app.tsxapps/docs/src/web/routes/_docs/routes/explicit-routing.tsxapps/docs/src/web/routes/_docs/routes/webrtc.tsxapps/docs/src/web/routes/_docs/services/email.tsxapps/docs/src/web/routes/_docs/services/schedules.tsxapps/docs/src/web/routes/_docs/services/tasks.tsxapps/docs/src/web/routes/_docs/services/webhooks.tsx
💤 Files with no reviewable changes (1)
- apps/docs/src/web/app.css
| ```typescript title="src/agent/handoffs/index.ts" | ||
| import { Agent, run, handoff, setTracingDisabled } from '@openai/agents'; | ||
| import { z } from 'zod'; | ||
|
|
||
| setTracingDisabled(true); | ||
|
|
||
| // Specialist agents with focused instructions | ||
| const billingAgent = new Agent({ | ||
| name: 'Billing Agent', | ||
| instructions: 'Help with invoice lookups and payment status.', | ||
| model: 'gpt-4.1', | ||
| tools: [lookupInvoice], | ||
| }); | ||
|
|
||
| const refundAgent = new Agent({ | ||
| name: 'Refund Agent', | ||
| instructions: 'Process refund requests immediately.', | ||
| model: 'gpt-4.1', | ||
| tools: [processRefund], | ||
| }); | ||
|
|
||
| // Typed escalation data for the refund handoff | ||
| const EscalationData = z.object({ | ||
| reason: z.string().describe('Why this is being escalated'), | ||
| }); | ||
|
|
||
| // Triage agent routes to specialists via handoffs | ||
| const triageAgent = Agent.create({ // [!code highlight] | ||
| name: 'Triage Agent', | ||
| instructions: `Route requests to the right specialist: | ||
| - Billing questions → Billing Agent | ||
| - Refund requests → Refund Agent (use escalate_to_refund)`, | ||
| model: 'gpt-4.1', | ||
| handoffs: [ | ||
| billingAgent, // basic handoff | ||
| handoff(refundAgent, { // [!code highlight] | ||
| onHandoff: (_ctx, input) => { | ||
| // _ctx is the OpenAI SDK's run context, not the Agentuity handler context | ||
| console.log('Refund escalation:', input?.reason); | ||
| }, | ||
| inputType: EscalationData, | ||
| toolNameOverride: 'escalate_to_refund', | ||
| }), | ||
| ], | ||
| }); | ||
| ``` |
There was a problem hiding this comment.
Make this handoff snippet runnable, and avoid console.log.
Lines 91 and 98 reference lookupInvoice / processRefund, but the snippet never defines or imports them, so readers can’t paste this file as shown. The same block also uses console.log on Line 118, which doesn’t match the docs convention for server/agent examples. Inline minimal tool stubs or imports, and move the logging back to an Agentuity ctx.logger path.
As per coding guidelines, "Use 'ctx.logger' in server/agent code examples, not 'console.log'" and "Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable."
🤖 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/openai-agents.mdx` around
lines 80 - 125, This snippet is missing tool definitions and uses console.log;
define or import minimal tool stubs for lookupInvoice and processRefund (e.g.,
simple objects/functions named lookupInvoice and processRefund used in
billingAgent and refundAgent), and replace the console.log in the handoff
onHandoff handler with the Agentuity logger (use the ctx parameter and call
ctx.logger.info or ctx.logger.debug) so the EscalationData-driven handoff is
runnable; update the handoff call (handoff(refundAgent, { onHandoff: (ctx,
input) => ctx.logger.info(`Refund escalation: ${input?.reason}`), inputType:
EscalationData, toolNameOverride: 'escalate_to_refund' })) and ensure these
edits are made alongside the triageAgent/Agent.create usage so the file is
copy-paste runnable.
| Create a queue from an agent or route using `ctx.queue.createQueue()`: | ||
|
|
||
| ```typescript | ||
| // Inside an agent handler or route | ||
| const result = await ctx.queue.createQueue('notifications', { // [!code highlight] | ||
| queueType: 'worker', | ||
| description: 'Order notifications', | ||
| settings: { | ||
| defaultTtlSeconds: 86400, // messages expire after 24 hours | ||
| defaultMaxRetries: 3, | ||
| }, | ||
| }); // [!code highlight] | ||
| ``` | ||
|
|
||
| ```typescript | ||
| interface QueueCreateResult { | ||
| name: string; // Queue name | ||
| queueType: string; // 'worker' or 'pubsub' | ||
| } | ||
| ``` | ||
|
|
||
| All parameters are optional. Omitting `queueType` defaults to `worker`. | ||
|
|
||
| | Option | Type | Description | | ||
| |--------|------|-------------| | ||
| | `queueType` | `'worker' \| 'pubsub'` | Worker for point-to-point, pubsub for broadcast (optional, defaults to `worker`) | | ||
| | `description` | `string` | Human-readable description (optional) | | ||
| | `settings.defaultTtlSeconds` | `number` | Message expiration window in seconds (optional) | | ||
| | `settings.defaultVisibilityTimeoutSeconds` | `number` | Visibility timeout after a message is received, before it returns to the queue (optional) | | ||
| | `settings.defaultMaxRetries` | `number` | Delivery retry limit before moving to DLQ (optional) | | ||
| | `settings.maxInFlightPerClient` | `number` | Concurrent message limit per consumer (optional) | | ||
| | `settings.retentionSeconds` | `number` | Retention period for acknowledged messages (optional) | | ||
|
|
||
| <Callout type="info" title="Idempotent Creation"> | ||
| `createQueue` is safe to call multiple times. If the queue already exists, it returns successfully without error. The SDK caches creation within the current request context, so duplicate calls in the same handler return immediately without additional API requests. | ||
| </Callout> |
There was a problem hiding this comment.
Bring this createQueue() section back in sync with the queue API.
This section currently conflicts with the queue types shown elsewhere in the repo: it uses ctx.queue.createQueue('notifications', { queueType: ... }), introduces a QueueCreateResult that is not reflected in packages/core/src/services/queue/queues.ts:68-72, and says queueType is optional even though packages/core/src/services/queue/types.ts:310-350 documents a single request object with name, queue_type, and snake_case settings. The page itself later switches back to snake_case in Queue Settings, so readers see two incompatible shapes on the same page. The idempotent-creation guarantee on Lines 77-79 also needs source-backed confirmation before it becomes part of the docs contract.
🤖 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 44 - 79, The docs
example and types are out of sync with the actual queue API: replace the current
call signature ctx.queue.createQueue('notifications', { queueType: ... }) and
the camelCase QueueCreateResult with the canonical single-request object shape
used by the service (use ctx.queue.createQueue({ name: 'notifications',
queue_type: 'worker', description: 'Order notifications', settings: {
default_ttl_seconds, default_visibility_timeout_seconds, default_max_retries,
max_in_flight_per_client, retention_seconds }}) and update the returned result
shape to match the service (snake_case fields), ensure the "Queue Settings"
section uses the same snake_case keys, and remove or revise the "Idempotent
Creation" claim unless you can reference the service implementation
(ctx.queue.createQueue) to confirm idempotency; if it is idempotent, add a short
source-backed note referencing the function/method that enforces it.
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (3)
apps/docs/src/web/content/get-started/app-configuration.mdx (1)
228-233:⚠️ Potential issue | 🟡 MinorComplete the file-order table to include
.env.local.The table at Line 228 currently shows
agentuity devloading.env → .env.development, but Line 257 says.env.localhas highest precedence. Put.env.localdirectly in the table so precedence is unambiguous in one place.Suggested doc patch
**File loading order:** | Mode | Files loaded (later overrides earlier) | |------|----------------------------------------| -| `agentuity dev` | `.env` → `.env.development` | +| `agentuity dev` | `.env` → `.env.development` → `.env.local` | When the same variable appears in multiple files, the last file loaded wins.Also applies to: 257-259
🤖 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 228 - 233, Update the "**File loading order:**" table row for "agentuity dev" to include ".env.local" as the last entry so the sequence reads ".env → .env.development → .env.local" (later overrides earlier), and make the same change for the duplicate table referenced around the later section (the passage that currently states ".env.local has highest precedence") so both places match and show .env.local as highest precedence.apps/docs/src/web/content/cookbook/integrations/langchain.mdx (1)
102-131:⚠️ Potential issue | 🟠 MajorInline the missing setup here or mark both blocks as explicit continuations.
Lines 103-158 still depend on undeclared
search,calculate,getTime,message,langchainAgent, andmessages, so a reader who copies either block hits errors before reaching the actual streaming or structured-output behavior. If the goal is brevity, make the partial nature explicit in the caption or prose instead of presenting them as standalone TypeScript snippets.As per coding guidelines, "Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable."
Also applies to: 139-160
🤖 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 102 - 131, The snippet shows streaming usage but references undeclared symbols (search, calculate, getTime, message, langchainAgent, messages); make the example copy-pastable by either inlining a brief setup or marking it as a continuation: add minimal declarations/import hints for search/calculate/getTime tool variables, define message/messages (e.g., a sample HumanMessage), and show the createAgent call (langchainAgent) or explicitly label the block as a continuation in the caption/prose so readers know they must include the prior setup; update the snippet around langchainAgent, stream, and the for-await loop to reference those provided names consistently.apps/docs/src/web/content/cookbook/integrations/openai-agents.mdx (1)
80-127:⚠️ Potential issue | 🟠 MajorMake the handoff example runnable and stop teaching
console.log.Lines 84-123 still rely on placeholder tool definitions for
lookupInvoiceandprocessRefund, so thesrc/agent/handoffs/index.tsexample cannot be copied into a project as shown. The note on Lines 118-120 also teachesconsole.logas the fallback logging pattern in a server-side example, which conflicts with the rest of the docs.As per coding guidelines, "Use 'ctx.logger' in server/agent code examples, not 'console.log'" and "Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable."
🤖 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/openai-agents.mdx` around lines 80 - 127, Provide runnable, copy-pasteable example code by adding concrete imports and simple stub tool implementations for lookupInvoice and processRefund (or import them if they exist) and replace the server-side console.log in the handoff onHandoff callback with ctx.logger (e.g., ctx.logger.info or ctx.logger.error) so logging follows project guidelines; specifically update the top of the snippet to import required symbols (Agent, run, handoff, setTracingDisabled, z) and define lookupInvoice and processRefund tool functions/objects referenced by billingAgent and refundAgent, and change the onHandoff signature to use the agent context (ctx) and call ctx.logger.info('Refund escalation:', input?.reason) instead of console.log so triageAgent's handoffs are runnable and consistent with server code examples.
🧹 Nitpick comments (3)
apps/docs/src/web/content/services/tasks.mdx (2)
440-473: Consider adding logging to route examples.The route examples demonstrate
c.var.taskaccess well, but unlike the agent examples, they don't include any logging. Adding a log statement (e.g., using Hono's logger middleware or a similar pattern) would make the examples more consistent with the logging shown in agent examples.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/tasks.mdx` around lines 440 - 473, The examples lack logging; update the router.post('/tasks', ...) and router.get('/tasks/:id', ...) handlers (created via createRouter) to emit log entries when a task is created, when a fetch is attempted, and when a task is not found — either hook Hono's logger middleware or call the contextual logger (e.g., c.log.info / c.log.error) inside those handlers before returning so the flows around c.var.task.create and c.var.task.get include descriptive log messages including ids and status.
2-3: Consider an action-oriented title.The title "Tasks" is noun-based. Per coding guidelines, documentation pages should use action-oriented titles (e.g., "Managing Tasks" or "Tracking Work Items with Tasks").
📝 Suggested title
--- -title: Tasks +title: Managing Tasks description: Track work items, issues, and agent activity with built-in lifecycle management ---As per coding guidelines: "Use action-oriented titles (e.g., 'Calling Other Agents' not 'Agent Communication') for documentation pages."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/services/tasks.mdx` around lines 2 - 3, Update the front-matter "title" value from the noun "Tasks" to an action-oriented phrase (for example, "Managing Tasks" or "Tracking Work Items with Tasks") so the page follows the docs guideline; modify the title field in the front-matter at the top of the file (the "title" key) to the chosen action-oriented string and keep the existing description unchanged.apps/docs/src/web/content/routes/webrtc.mdx (1)
376-376: Consider varying sentence structure.Three consecutive sentences start with "Use", which reads repetitively. A minor rephrase improves flow.
✏️ Suggested rewrite
-Use WebRTC when you need **peer-to-peer** connections or **media streaming**. Use [WebSockets](/routes/websockets) when you need **server-mediated** bidirectional communication. Use [SSE](/routes/sse) for **server-to-client** streaming. +WebRTC is ideal for **peer-to-peer** connections and **media streaming**. For **server-mediated** bidirectional communication, see [WebSockets](/routes/websockets). For **server-to-client** streaming, see [SSE](/routes/sse).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/routes/webrtc.mdx` at line 376, Change the three consecutive sentences that all begin with "Use" (the sentence starting "Use WebRTC when you need peer-to-peer...", the one starting "Use [WebSockets](/routes/websockets) when you need...", and the one starting "Use [SSE](/routes/sse) for...") to vary sentence structure for better flow — e.g., keep the first as-is, rephrase the second to "Choose WebSockets when you need server-mediated bidirectional communication" and the third to "For server-to-client streaming, consider SSE" (or similar wording) so each sentence starts differently while preserving the original meaning and links.
🤖 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/get-started/app-configuration.mdx`:
- Around line 251-253: Replace the Callout component that currently uses
type="tip" (the Callout with title "Separate Files, Not Comments") with
type="info" so the message is rendered as contextual clarification; keep the
title and content unchanged and only modify the Callout's type attribute to
"info".
In `@apps/docs/src/web/content/routes/webrtc.mdx`:
- Around line 207-229: Add the missing import for the custom hook so the example
is copy-paste runnable: at the top of the snippet import useWebRTCCall from the
library used by the component (the hook referenced as useWebRTCCall) — this
ensures VideoCallWithErrorHandling can call useWebRTCCall (signalUrl/callbacks)
without throwing a missing-symbol error.
- Around line 148-165: The Hook Options table is missing the callbacks option
defined on the UseWebRTCCallOptions interface and referenced in useWebRTCCall
examples; add a new row to the Markdown table describing `callbacks` (type
`Partial<UseWebRTCCallCallbacks>` or the documented callback type used in the
code), its default (e.g., `undefined`), and a short description of what
callbacks are for (events like onConnect, onDisconnect, onTrack, onData, etc.)
so the documentation matches the actual UseWebRTCCallOptions interface and the
examples that use it.
In `@apps/docs/src/web/content/services/tasks.mdx`:
- Around line 92-99: Update the callout text to clarify that status alias
normalization happens in the SDK on the client side by calling
normalizeTaskStatus() during the SDK's create() flow (not on the server);
mention normalizeTaskStatus() and create() explicitly and change phrasing like
"normalize to canonical statuses before saving" to "SDK normalizes aliases via
normalizeTaskStatus() in the create() request before sending to the server."
---
Duplicate comments:
In `@apps/docs/src/web/content/cookbook/integrations/langchain.mdx`:
- Around line 102-131: The snippet shows streaming usage but references
undeclared symbols (search, calculate, getTime, message, langchainAgent,
messages); make the example copy-pastable by either inlining a brief setup or
marking it as a continuation: add minimal declarations/import hints for
search/calculate/getTime tool variables, define message/messages (e.g., a sample
HumanMessage), and show the createAgent call (langchainAgent) or explicitly
label the block as a continuation in the caption/prose so readers know they must
include the prior setup; update the snippet around langchainAgent, stream, and
the for-await loop to reference those provided names consistently.
In `@apps/docs/src/web/content/cookbook/integrations/openai-agents.mdx`:
- Around line 80-127: Provide runnable, copy-pasteable example code by adding
concrete imports and simple stub tool implementations for lookupInvoice and
processRefund (or import them if they exist) and replace the server-side
console.log in the handoff onHandoff callback with ctx.logger (e.g.,
ctx.logger.info or ctx.logger.error) so logging follows project guidelines;
specifically update the top of the snippet to import required symbols (Agent,
run, handoff, setTracingDisabled, z) and define lookupInvoice and processRefund
tool functions/objects referenced by billingAgent and refundAgent, and change
the onHandoff signature to use the agent context (ctx) and call
ctx.logger.info('Refund escalation:', input?.reason) instead of console.log so
triageAgent's handoffs are runnable and consistent with server code examples.
In `@apps/docs/src/web/content/get-started/app-configuration.mdx`:
- Around line 228-233: Update the "**File loading order:**" table row for
"agentuity dev" to include ".env.local" as the last entry so the sequence reads
".env → .env.development → .env.local" (later overrides earlier), and make the
same change for the duplicate table referenced around the later section (the
passage that currently states ".env.local has highest precedence") so both
places match and show .env.local as highest precedence.
---
Nitpick comments:
In `@apps/docs/src/web/content/routes/webrtc.mdx`:
- Line 376: Change the three consecutive sentences that all begin with "Use"
(the sentence starting "Use WebRTC when you need peer-to-peer...", the one
starting "Use [WebSockets](/routes/websockets) when you need...", and the one
starting "Use [SSE](/routes/sse) for...") to vary sentence structure for better
flow — e.g., keep the first as-is, rephrase the second to "Choose WebSockets
when you need server-mediated bidirectional communication" and the third to "For
server-to-client streaming, consider SSE" (or similar wording) so each sentence
starts differently while preserving the original meaning and links.
In `@apps/docs/src/web/content/services/tasks.mdx`:
- Around line 440-473: The examples lack logging; update the
router.post('/tasks', ...) and router.get('/tasks/:id', ...) handlers (created
via createRouter) to emit log entries when a task is created, when a fetch is
attempted, and when a task is not found — either hook Hono's logger middleware
or call the contextual logger (e.g., c.log.info / c.log.error) inside those
handlers before returning so the flows around c.var.task.create and
c.var.task.get include descriptive log messages including ids and status.
- Around line 2-3: Update the front-matter "title" value from the noun "Tasks"
to an action-oriented phrase (for example, "Managing Tasks" or "Tracking Work
Items with Tasks") so the page follows the docs guideline; modify the title
field in the front-matter at the top of the file (the "title" key) to the chosen
action-oriented string and keep the existing description unchanged.
🪄 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: 28f350c8-5201-4fe4-a31b-2bb8dc94e385
📒 Files selected for processing (7)
apps/docs/src/web/content/cookbook/integrations/langchain.mdxapps/docs/src/web/content/cookbook/integrations/mastra.mdxapps/docs/src/web/content/cookbook/integrations/openai-agents.mdxapps/docs/src/web/content/get-started/app-configuration.mdxapps/docs/src/web/content/reference/cli/deployment.mdxapps/docs/src/web/content/routes/webrtc.mdxapps/docs/src/web/content/services/tasks.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- apps/docs/src/web/content/cookbook/integrations/mastra.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). (15)
- GitHub Check: Agentuity Deployment
- GitHub Check: Framework Integration Tests (TanStack & Next.js)
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Queue CLI Tests
- GitHub Check: Queue SDK Tests
- GitHub Check: Package Installation & Usage Test
- GitHub Check: Sandbox CLI Tests
- GitHub Check: Storage CLI Tests
- GitHub Check: Standalone Agent Test
- GitHub Check: SDK Integration Test Suite
- GitHub Check: Template Integration Tests
- GitHub Check: Cloud Deployment Tests
- GitHub Check: Postgres SSL Integration Test
- GitHub Check: Build
- GitHub Check: Pack & Upload
🧰 Additional context used
📓 Path-based instructions (1)
apps/docs/src/web/content/**/*.mdx
📄 CodeRabbit inference engine (apps/docs/src/web/content/AGENTS.md)
apps/docs/src/web/content/**/*.mdx: Write 1-2 sentences of motivation before showing code (context-then-code principle)
Use 'ctx.logger' in server/agent code examples, not 'console.log'
Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable
Use inline comments to explain intent ('why'), not syntax ('what')
Do not use suppression comments like '//@ts-ignore', '// eslint-disable', or other code suppressions in documentation examples
Use action-oriented titles (e.g., 'Calling Other Agents' not 'Agent Communication') for documentation pages
Keep feature documentation provider-agnostic where possible; use current model names in code examples and verify they are up to date before publishing
Use 'info' callout type for context and clarifications, 'warning' for gotchas and required setup, 'tip' for optimizations and advanced patterns
Make cross-links context-specific: include why the reader would follow the link (e.g., 'See Streaming Responses for chunked output patterns')
Link to external tools on first mention only; do not re-link on the same page
Replace hollow adjectives (e.g., 'powerful', 'seamless', 'enterprise-grade') with specific benefits; use precise language like 'consistent API', 'type-safe', 'observable', 'faster'
Explicitly mark optional parameters as 'optional' in prose; readers should not need to parse type signatures
Use inline code references to show API shape, config values, or method signatures without imports; use standalone examples for concepts that require copy-pasteable code
Prefer 'Prefersfrom@agentuity/schemafor schemas; show schema-agnostic SDK examples using other StandardSchema libraries (Zod, ArkType, Valibot) across documentation
Use a balance of raw SDK providers and AI SDK providers (openai(),anthropic()) in code examples throughout documentation
Strip boilerplate from code examples; show only the feature being demonstrated
Files:
apps/docs/src/web/content/reference/cli/deployment.mdxapps/docs/src/web/content/services/tasks.mdxapps/docs/src/web/content/cookbook/integrations/langchain.mdxapps/docs/src/web/content/get-started/app-configuration.mdxapps/docs/src/web/content/routes/webrtc.mdxapps/docs/src/web/content/cookbook/integrations/openai-agents.mdx
🪛 LanguageTool
apps/docs/src/web/content/routes/webrtc.mdx
[style] ~376-~376: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...mediated** bidirectional communication. Use SSE for **server-to-clie...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
apps/docs/src/web/content/cookbook/integrations/openai-agents.mdx
[grammar] ~8-~8: Use a hyphen to join words.
Context: ...y manages everything around it. ## Tool Calling Agent Define tools with the Ope...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (17)
apps/docs/src/web/content/services/tasks.mdx (3)
265-278: LGTM!The attachment upload flow correctly checks
uploadResponse.okbefore callingconfirmAttachment(), preventing broken attachment records when uploads fail. This addresses the error handling concern appropriately.
36-62: LGTM!The code example includes the required import, uses
ctx.loggerfor logging, and includes an inline comment explaining intent ("distinguish from human users"). The example is copy-pasteable and demonstrates the feature effectively.
475-487: LGTM!The Best Practices and Next Steps sections provide actionable guidance. Cross-links include context explaining why readers would follow them (e.g., "Async message passing for background processing between agents"), which aligns with coding guidelines.
apps/docs/src/web/content/get-started/app-configuration.mdx (1)
128-189: Nice addition: clear resource/build split and practical deploy script guidance.This section is easy to follow, and the examples are scoped well for copy/paste reference.
apps/docs/src/web/content/reference/cli/deployment.mdx (7)
248-254: LGTM!The re-linking issue from the previous review has been addressed—"Web App" is now plain text here since it was already linked earlier in the document.
263-265: LGTM!The callout type change from
infotowarningcorrectly emphasizes this as a required prerequisite. Cross-links are context-specific and explain why the reader would follow them.
30-52: LGTM!The
.envfile reference is now consistent throughout the document, and the Web App link is appropriately placed at first mention.
392-400: LGTM!Resource configuration example is clear and the documented defaults match the example values.
404-443: LGTM!This new section clearly distinguishes between runtime (
deployment.resources) and build-time (build) resource configuration. The tip callout appropriately guides readers on when to override build resources, and optional fields are explicitly marked.
447-454: LGTM!The
.envfile reference is consistent with the deploy command description earlier in the document.
526-551: LGTM!This section clearly documents lifecycle script conventions. The warning callout appropriately highlights the behavioral difference between
bun run deploy(lifecycle hooks run) andagentuity deploy(they don't), which is a key gotcha. The cross-links to GitHub App build process provide context for readers who deploy via that integration.apps/docs/src/web/content/routes/webrtc.mdx (6)
170-185: Hook called at module scope violates React's Rules of Hooks.This code block shows
useWebRTCCalldestructuring outside a component function, which is invalid React syntax. Wrap in a component or add a note that this must run inside a component.
191-201: Hook called at module scope.Same issue as the Data Channel Methods section—wrap in a component or note the context requirement.
249-263: Hook called at module scope; missing import.Same issue flagged previously—wrap in a component and add the import statement.
287-314: Hook called at module scope; missing import.Same issue flagged previously—wrap in a component and add the import statement.
344-363: Hook called at module scope.Same issue flagged previously—wrap these examples in component context.
16-25: LGTM!The inline comment on line 21 now clearly explains that the full endpoint path is
/api/call/signaldue to the file path (src/api/call/) plus the registered route (/signal). This resolves the previous concern about endpoint inconsistency.
| <Callout type="info" title="Status aliases"> | ||
| The SDK accepts shorthand values that normalize to canonical statuses before saving: | ||
|
|
||
| - `completed` and `closed` both normalize to `done` | ||
| - `started` normalizes to `in_progress` | ||
|
|
||
| The four canonical statuses are `open`, `in_progress`, `done`, and `cancelled`. Use these in queries and comparisons. | ||
| </Callout> |
There was a problem hiding this comment.
Clarify that normalization happens SDK-side, not server-side.
The callout states aliases "normalize to canonical statuses before saving," which implies server-side processing. However, based on the SDK implementation, normalizeTaskStatus() is called client-side in the SDK's create() method before the request is sent to the server. Consider updating the wording to clarify this.
📝 Suggested clarification
<Callout type="info" title="Status aliases">
-The SDK accepts shorthand values that normalize to canonical statuses before saving:
+The SDK normalizes shorthand values to canonical statuses before sending them to the server:
- `completed` and `closed` both normalize to `done`
- `started` normalizes to `in_progress`
-The four canonical statuses are `open`, `in_progress`, `done`, and `cancelled`. Use these in queries and comparisons.
+The four canonical statuses are `open`, `in_progress`, `done`, and `cancelled`. Since normalization happens client-side, use canonical statuses in queries and comparisons.
</Callout>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/src/web/content/services/tasks.mdx` around lines 92 - 99, Update
the callout text to clarify that status alias normalization happens in the SDK
on the client side by calling normalizeTaskStatus() during the SDK's create()
flow (not on the server); mention normalizeTaskStatus() and create() explicitly
and change phrasing like "normalize to canonical statuses before saving" to "SDK
normalizes aliases via normalizeTaskStatus() in the create() request before
sending to the server."
- Update model names to `gpt-5.4` - Fix weather tool to use location input - Fix WebRTC signal paths and hook scope - Add upload error check in tasks attachment - Clarify `.env.local` precedence
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
apps/docs/src/web/content/get-started/app-configuration.mdx (1)
228-259:⚠️ Potential issue | 🟡 MinorUnify
.env.localprecedence directly in the load-order table.Line 232 documents
agentuity devload order without.env.local, while Line 257 later states.env.localhas highest precedence. Bringing.env.localinto the same table would make precedence unambiguous in one place.Suggested docs patch
| Mode | Files loaded (later overrides earlier) | |------|----------------------------------------| -| `agentuity dev` | `.env` → `.env.development` | +| `agentuity dev` | `.env` → `.env.development` → `.env.local` |🤖 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 228 - 259, Update the "File loading order" table under the "File loading order:" heading to include `.env.local` as the last/highest-precedence file for the `agentuity dev` row (e.g., `.env` → `.env.development` → `.env.local`), and remove the duplicated precedence note later by consolidating the `.env.local` explanation into the "Additional files" bullet so the precedence is unambiguous in one place; ensure the `.env.local` note still states it is usually gitignored and has highest precedence (Bun-specific behavior) and keep the example and callout text unchanged.
🧹 Nitpick comments (1)
apps/docs/src/web/content/get-started/app-configuration.mdx (1)
178-184: Make the deploy script example project-agnostic.The
predeployexample currently includes monorepo-specific setup (cd ../..andbuild:packages), which adds noise for most readers and weakens reusability.Suggested docs patch
{ "scripts": { - "predeploy": "cd ../.. && bun install && bun run build:packages", + "predeploy": "bun install && bun run build", "deploy": "agentuity deploy", "postdeploy": "echo 'Deploy complete'" } }As per coding guidelines, "Strip boilerplate from code examples; show only the feature being demonstrated".
🤖 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 178 - 184, The package.json example's "predeploy" script contains monorepo-specific commands ("cd ../.." and "bun run build:packages") that should be removed to keep the example project-agnostic; update the "scripts" object so "predeploy" only runs the generic setup needed for deployment (e.g., "bun install" or the project's standard build command like "bun run build" or "npm install && npm run build"), leaving "deploy" as "agentuity deploy" and "postdeploy" unchanged; locate the package.json snippet and replace the value of the "predeploy" key in the "scripts" block accordingly.
🤖 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/routes/webrtc.mdx`:
- Around line 157-165: Update the WebRTC options table descriptions to
explicitly mark optional parameters in prose: for the rows with symbols
dataChannels, autoConnect, autoReconnect, maxReconnectAttempts, polite,
iceServers, and callbacks (and any other fields that rely on defaults like
connectionTimeout and iceGatheringTimeout), append "(optional)" to their
description text so readers don't need to inspect types to know they're
optional; keep the existing default values and brief descriptions but ensure the
prose contains the word "optional" for each optional parameter.
- Line 165: The docs table entry for the `callbacks` prop lists callback names
as `onConnected`/`onDisconnected` but the actual interface is
`WebRTCClientCallbacks` which exposes `onConnect` and `onDisconnect`; update the
documentation row (the `callbacks` prop description) to use `onConnect` and
`onDisconnect` to match the `WebRTCClientCallbacks` interface and ensure the
wording mentions other callbacks like `onError` consistently.
---
Duplicate comments:
In `@apps/docs/src/web/content/get-started/app-configuration.mdx`:
- Around line 228-259: Update the "File loading order" table under the "File
loading order:" heading to include `.env.local` as the last/highest-precedence
file for the `agentuity dev` row (e.g., `.env` → `.env.development` →
`.env.local`), and remove the duplicated precedence note later by consolidating
the `.env.local` explanation into the "Additional files" bullet so the
precedence is unambiguous in one place; ensure the `.env.local` note still
states it is usually gitignored and has highest precedence (Bun-specific
behavior) and keep the example and callout text unchanged.
---
Nitpick comments:
In `@apps/docs/src/web/content/get-started/app-configuration.mdx`:
- Around line 178-184: The package.json example's "predeploy" script contains
monorepo-specific commands ("cd ../.." and "bun run build:packages") that should
be removed to keep the example project-agnostic; update the "scripts" object so
"predeploy" only runs the generic setup needed for deployment (e.g., "bun
install" or the project's standard build command like "bun run build" or "npm
install && npm run build"), leaving "deploy" as "agentuity deploy" and
"postdeploy" unchanged; locate the package.json snippet and replace the value of
the "predeploy" key in the "scripts" block accordingly.
🪄 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: c6cb59e4-03df-4333-8ae7-1bc55eaaf7fb
📒 Files selected for processing (3)
apps/docs/src/web/content/get-started/app-configuration.mdxapps/docs/src/web/content/routes/webrtc.mdxapps/docs/src/web/content/services/tasks.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- apps/docs/src/web/content/services/tasks.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). (15)
- GitHub Check: Agentuity Deployment
- GitHub Check: Build
- GitHub Check: Queue CLI Tests
- GitHub Check: Template Integration Tests
- GitHub Check: Standalone Agent Test
- GitHub Check: Sandbox CLI Tests
- GitHub Check: Package Installation & Usage Test
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Framework Integration Tests (TanStack & Next.js)
- GitHub Check: Queue SDK Tests
- GitHub Check: SDK Integration Test Suite
- GitHub Check: Postgres SSL Integration Test
- GitHub Check: Storage CLI Tests
- GitHub Check: Cloud Deployment Tests
- GitHub Check: Pack & Upload
🧰 Additional context used
📓 Path-based instructions (1)
apps/docs/src/web/content/**/*.mdx
📄 CodeRabbit inference engine (apps/docs/src/web/content/AGENTS.md)
apps/docs/src/web/content/**/*.mdx: Write 1-2 sentences of motivation before showing code (context-then-code principle)
Use 'ctx.logger' in server/agent code examples, not 'console.log'
Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable
Use inline comments to explain intent ('why'), not syntax ('what')
Do not use suppression comments like '//@ts-ignore', '// eslint-disable', or other code suppressions in documentation examples
Use action-oriented titles (e.g., 'Calling Other Agents' not 'Agent Communication') for documentation pages
Keep feature documentation provider-agnostic where possible; use current model names in code examples and verify they are up to date before publishing
Use 'info' callout type for context and clarifications, 'warning' for gotchas and required setup, 'tip' for optimizations and advanced patterns
Make cross-links context-specific: include why the reader would follow the link (e.g., 'See Streaming Responses for chunked output patterns')
Link to external tools on first mention only; do not re-link on the same page
Replace hollow adjectives (e.g., 'powerful', 'seamless', 'enterprise-grade') with specific benefits; use precise language like 'consistent API', 'type-safe', 'observable', 'faster'
Explicitly mark optional parameters as 'optional' in prose; readers should not need to parse type signatures
Use inline code references to show API shape, config values, or method signatures without imports; use standalone examples for concepts that require copy-pasteable code
Prefer 'Prefersfrom@agentuity/schemafor schemas; show schema-agnostic SDK examples using other StandardSchema libraries (Zod, ArkType, Valibot) across documentation
Use a balance of raw SDK providers and AI SDK providers (openai(),anthropic()) in code examples throughout documentation
Strip boilerplate from code examples; show only the feature being demonstrated
Files:
apps/docs/src/web/content/get-started/app-configuration.mdxapps/docs/src/web/content/routes/webrtc.mdx
🪛 LanguageTool
apps/docs/src/web/content/routes/webrtc.mdx
[style] ~379-~379: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...mediated** bidirectional communication. Use SSE for **server-to-clie...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (2)
apps/docs/src/web/content/get-started/app-configuration.mdx (1)
130-173: Strong addition: deployment/build resource docs align with actual config shape.This section is clear and matches the CLI config model (
deployment.resources,deployment.domains,build.timeout,build.resources) and usage.apps/docs/src/web/content/routes/webrtc.mdx (1)
21-23: Nice route-path clarification and client/server alignment.The note at Line 21 removes ambiguity and now matches the client
signalUrlexamples.
| | `dataChannels` | `DataChannelConfig[]` | `undefined` | Data channels to create | | ||
| | `autoConnect` | `boolean` | `true` | Connect on mount | | ||
| | `autoReconnect` | `boolean` | `true` | Reconnect on failure | | ||
| | `maxReconnectAttempts` | `number` | `5` | Max reconnection attempts | | ||
| | `polite` | `boolean` | `undefined` | Perfect negotiation role | | ||
| | `connectionTimeout` | `number` | `30000` | Milliseconds before connection attempt times out (optional) | | ||
| | `iceGatheringTimeout` | `number` | `10000` | Milliseconds before ICE gathering times out (optional) | | ||
| | `iceServers` | `RTCIceServer[]` | STUN defaults | ICE/TURN server configuration | | ||
| | `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Connection lifecycle callbacks (`onConnected`, `onDisconnected`, `onError`, etc.) | |
There was a problem hiding this comment.
Mark optional hook options explicitly in prose for consistency.
Several optional options are implied by defaults but not labeled as optional (for example dataChannels, autoConnect, autoReconnect, maxReconnectAttempts, polite, iceServers, callbacks).
✏️ Suggested table wording update
-| `dataChannels` | `DataChannelConfig[]` | `undefined` | Data channels to create |
-| `autoConnect` | `boolean` | `true` | Connect on mount |
-| `autoReconnect` | `boolean` | `true` | Reconnect on failure |
-| `maxReconnectAttempts` | `number` | `5` | Max reconnection attempts |
-| `polite` | `boolean` | `undefined` | Perfect negotiation role |
-| `iceServers` | `RTCIceServer[]` | STUN defaults | ICE/TURN server configuration |
-| `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Connection lifecycle callbacks (`onConnected`, `onDisconnected`, `onError`, etc.) |
+| `dataChannels` | `DataChannelConfig[]` | `undefined` | Data channels to create (optional) |
+| `autoConnect` | `boolean` | `true` | Connect on mount (optional) |
+| `autoReconnect` | `boolean` | `true` | Reconnect on failure (optional) |
+| `maxReconnectAttempts` | `number` | `5` | Max reconnection attempts (optional) |
+| `polite` | `boolean` | `undefined` | Perfect negotiation role (optional) |
+| `iceServers` | `RTCIceServer[]` | STUN defaults | ICE/TURN server configuration (optional) |
+| `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Connection lifecycle callbacks (`onConnect`, `onDisconnect`, `onError`, etc.) (optional) |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/src/web/content/routes/webrtc.mdx` around lines 157 - 165, Update
the WebRTC options table descriptions to explicitly mark optional parameters in
prose: for the rows with symbols dataChannels, autoConnect, autoReconnect,
maxReconnectAttempts, polite, iceServers, and callbacks (and any other fields
that rely on defaults like connectionTimeout and iceGatheringTimeout), append
"(optional)" to their description text so readers don't need to inspect types to
know they're optional; keep the existing default values and brief descriptions
but ensure the prose contains the word "optional" for each optional parameter.
| | `connectionTimeout` | `number` | `30000` | Milliseconds before connection attempt times out (optional) | | ||
| | `iceGatheringTimeout` | `number` | `10000` | Milliseconds before ICE gathering times out (optional) | | ||
| | `iceServers` | `RTCIceServer[]` | STUN defaults | ICE/TURN server configuration | | ||
| | `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Connection lifecycle callbacks (`onConnected`, `onDisconnected`, `onError`, etc.) | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Locate relevant files =="
fd "webrtc.tsx" --type f
fd "webrtc-manager.ts" --type f
echo "== Verify UseWebRTCCallResult members =="
rg -n -C2 'export interface UseWebRTCCallResult|sendJSON|closeDataChannel|getQualitySummary|getAllQualitySummaries|startRecording|stopAllRecordings|createDataChannel|sendString|sendBinary' packages/react/src/webrtc.tsx
echo "== Verify callback names =="
rg -n -C2 'export interface WebRTCClientCallbacks|onConnect|onDisconnect|onConnected|onDisconnected|onError|onReconnecting|onReconnectFailed' packages/frontend/src/webrtc-manager.tsRepository: agentuity/sdk
Length of output: 8450
🏁 Script executed:
cd apps/docs && cat -n src/web/routes/_docs/routes/webrtc.mdx | sed -n '160,180p'Repository: agentuity/sdk
Length of output: 127
🏁 Script executed:
cd apps/docs && cat -n src/web/routes/_docs/routes/webrtc.mdx | sed -n '248,260p'Repository: agentuity/sdk
Length of output: 127
🏁 Script executed:
cd apps/docs && cat -n src/web/routes/_docs/routes/webrtc.mdx | sed -n '288,300p'Repository: agentuity/sdk
Length of output: 127
🏁 Script executed:
fd "webrtc.mdx" apps/docs --type fRepository: agentuity/sdk
Length of output: 100
🏁 Script executed:
cat -n apps/docs/src/web/content/routes/webrtc.mdx | sed -n '160,180p'Repository: agentuity/sdk
Length of output: 1139
🏁 Script executed:
cat -n apps/docs/src/web/content/routes/webrtc.mdx | sed -n '168,190p'Repository: agentuity/sdk
Length of output: 737
🏁 Script executed:
cat -n apps/docs/src/web/content/routes/webrtc.mdx | sed -n '248,320p'Repository: agentuity/sdk
Length of output: 3274
Fix callback name typos in WebRTCClientCallbacks documentation.
Line 165 documents callback names as onConnected and onDisconnected, but the actual interface uses onConnect and onDisconnect.
Correction
-| `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Connection lifecycle callbacks (`onConnected`, `onDisconnected`, `onError`, etc.) |
+| `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Connection lifecycle callbacks (`onConnect`, `onDisconnect`, `onError`, etc.) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Connection lifecycle callbacks (`onConnected`, `onDisconnected`, `onError`, etc.) | | |
| | `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Connection lifecycle callbacks (`onConnect`, `onDisconnect`, `onError`, etc.) | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/src/web/content/routes/webrtc.mdx` at line 165, The docs table
entry for the `callbacks` prop lists callback names as
`onConnected`/`onDisconnected` but the actual interface is
`WebRTCClientCallbacks` which exposes `onConnect` and `onDisconnect`; update the
documentation row (the `callbacks` prop description) to use `onConnect` and
`onDisconnect` to match the `WebRTCClientCallbacks` interface and ensure the
wording mentions other callbacks like `onError` consistently.
There was a problem hiding this comment.
♻️ Duplicate comments (2)
apps/docs/src/web/content/routes/webrtc.mdx (2)
157-165:⚠️ Potential issue | 🟡 MinorMark optional hook options explicitly in prose.
Several optional fields are still described without the word “optional” (for example
dataChannels,autoConnect,autoReconnect,maxReconnectAttempts,polite,connectionTimeout,iceGatheringTimeout,iceServers,callbacks), which makes the table harder to scan.✏️ Proposed doc tweak
-| `dataChannels` | `DataChannelConfig[]` | `undefined` | Data channels to create | -| `autoConnect` | `boolean` | `true` | Connect on mount | -| `autoReconnect` | `boolean` | `true` | Reconnect on failure | -| `maxReconnectAttempts` | `number` | `5` | Max reconnection attempts | -| `polite` | `boolean` | `undefined` | Perfect negotiation role | -| `connectionTimeout` | `number` | `30000` | Milliseconds before connection attempt times out | -| `iceGatheringTimeout` | `number` | `10000` | Milliseconds before ICE gathering times out | -| `iceServers` | `RTCIceServer[]` | STUN defaults | ICE/TURN server configuration | -| `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Lifecycle callbacks (`onStateChange`, `onError`, `onReconnecting`, `onReconnectFailed`) | +| `dataChannels` | `DataChannelConfig[]` | `undefined` | Data channels to create (optional) | +| `autoConnect` | `boolean` | `true` | Connect on mount (optional) | +| `autoReconnect` | `boolean` | `true` | Reconnect on failure (optional) | +| `maxReconnectAttempts` | `number` | `5` | Max reconnection attempts (optional) | +| `polite` | `boolean` | `undefined` | Perfect negotiation role (optional) | +| `connectionTimeout` | `number` | `30000` | Milliseconds before connection attempt times out (optional) | +| `iceGatheringTimeout` | `number` | `10000` | Milliseconds before ICE gathering times out (optional) | +| `iceServers` | `RTCIceServer[]` | STUN defaults | ICE/TURN server configuration (optional) | +| `callbacks` | `Partial<WebRTCClientCallbacks>` | `undefined` | Lifecycle callbacks (`onStateChange`, `onError`, `onReconnecting`, `onReconnectFailed`) (optional) |As per coding guidelines, "Explicitly mark optional parameters as 'optional' in prose; readers should not need to parse type signatures."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/routes/webrtc.mdx` around lines 157 - 165, Update the table rows for the WebRTC client hook options so optional fields explicitly state "optional" in the prose; for each of dataChannels (DataChannelConfig[]), autoConnect, autoReconnect, maxReconnectAttempts, polite, connectionTimeout, iceGatheringTimeout, iceServers (RTCIceServer[]), and callbacks (Partial<WebRTCClientCallbacks>) append or include "(optional)" in the description column (e.g., "Data channels to create (optional)", "Connect on mount (optional)") so readers don't need to parse the type signatures to know these are optional.
171-203:⚠️ Potential issue | 🟠 MajorMove
useWebRTCCall()examples into components/custom hooks and make snippets runnable.These snippets invoke
useWebRTCCall()at module scope and rely on undeclared values (peerId,remotePeerId,roomId), so they violate React hook rules and are not copy-paste runnable as written.🧩 Suggested pattern (apply to each snippet)
+import { useWebRTCCall } from '@agentuity/react'; + -const { sendString, sendStringTo } = useWebRTCCall({ /* ...options */ }); -sendString('chat', 'Hello everyone'); +function DataChannelExamples({ roomId, peerId }: { roomId: string; peerId: string }) { + const { sendString, sendStringTo } = useWebRTCCall({ + roomId, + signalUrl: '/api/call/signal', + media: false, + }); + + sendString('chat', 'Hello everyone'); + sendStringTo(peerId, 'chat', 'Private message'); + return null; +}As per coding guidelines, "Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable."
Also applies to: 209-219, 269-283, 307-337, 366-373, 381-385
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/routes/webrtc.mdx` around lines 171 - 203, The examples call useWebRTCCall at module scope and reference undeclared variables (peerId/remotePeerId/roomId), violating React hook rules and making snippets unrunnable; move each usage of useWebRTCCall (and functions like sendString, sendStringTo, sendJSON, sendJSONTo, sendBinary, sendBinaryTo, createDataChannel, getDataChannelLabels, getDataChannelState, closeDataChannel) inside a React component or a custom hook, add the necessary imports at the top, and declare or derive peerId/remotePeerId/roomId from props, state, or context so the snippets are copy-paste runnable while preserving the same function names and call patterns.
🧹 Nitpick comments (1)
apps/docs/src/web/content/routes/webrtc.mdx (1)
399-399: Consider varying sentence openings for readability.Three consecutive sentences start with “Use”; rephrasing one improves flow without changing meaning.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/web/content/routes/webrtc.mdx` at line 399, The three consecutive sentences beginning "Use WebRTC when you need **peer-to-peer** connections or **media streaming**.", "Use [WebSockets](/routes/websockets) when you need **server-mediated** bidirectional communication.", and "Use [SSE](/routes/sse) for **server-to-client** streaming." should vary their openings for better flow; rewrite one sentence (for example, start the second with "Opt for [WebSockets]..." or the third with "Choose [SSE]..." or combine/reorder phrases) so the meaning remains identical but the sentence starters are not all "Use".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@apps/docs/src/web/content/routes/webrtc.mdx`:
- Around line 157-165: Update the table rows for the WebRTC client hook options
so optional fields explicitly state "optional" in the prose; for each of
dataChannels (DataChannelConfig[]), autoConnect, autoReconnect,
maxReconnectAttempts, polite, connectionTimeout, iceGatheringTimeout, iceServers
(RTCIceServer[]), and callbacks (Partial<WebRTCClientCallbacks>) append or
include "(optional)" in the description column (e.g., "Data channels to create
(optional)", "Connect on mount (optional)") so readers don't need to parse the
type signatures to know these are optional.
- Around line 171-203: The examples call useWebRTCCall at module scope and
reference undeclared variables (peerId/remotePeerId/roomId), violating React
hook rules and making snippets unrunnable; move each usage of useWebRTCCall (and
functions like sendString, sendStringTo, sendJSON, sendJSONTo, sendBinary,
sendBinaryTo, createDataChannel, getDataChannelLabels, getDataChannelState,
closeDataChannel) inside a React component or a custom hook, add the necessary
imports at the top, and declare or derive peerId/remotePeerId/roomId from props,
state, or context so the snippets are copy-paste runnable while preserving the
same function names and call patterns.
---
Nitpick comments:
In `@apps/docs/src/web/content/routes/webrtc.mdx`:
- Line 399: The three consecutive sentences beginning "Use WebRTC when you need
**peer-to-peer** connections or **media streaming**.", "Use
[WebSockets](/routes/websockets) when you need **server-mediated** bidirectional
communication.", and "Use [SSE](/routes/sse) for **server-to-client**
streaming." should vary their openings for better flow; rewrite one sentence
(for example, start the second with "Opt for [WebSockets]..." or the third with
"Choose [SSE]..." or combine/reorder phrases) so the meaning remains identical
but the sentence starters are not all "Use".
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8335b1c1-a13e-4cb8-8130-350fc985c3c8
📒 Files selected for processing (1)
apps/docs/src/web/content/routes/webrtc.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). (15)
- GitHub Check: Agentuity Deployment
- GitHub Check: Template Integration Tests
- GitHub Check: Cloud Deployment Tests
- GitHub Check: Queue CLI Tests
- GitHub Check: Build
- GitHub Check: Pack & Upload
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Sandbox CLI Tests
- GitHub Check: Framework Integration Tests (TanStack & Next.js)
- GitHub Check: Postgres SSL Integration Test
- GitHub Check: Standalone Agent Test
- GitHub Check: Storage CLI Tests
- GitHub Check: SDK Integration Test Suite
- GitHub Check: Package Installation & Usage Test
- GitHub Check: Queue SDK Tests
🧰 Additional context used
📓 Path-based instructions (1)
apps/docs/src/web/content/**/*.mdx
📄 CodeRabbit inference engine (apps/docs/src/web/content/AGENTS.md)
apps/docs/src/web/content/**/*.mdx: Write 1-2 sentences of motivation before showing code (context-then-code principle)
Use 'ctx.logger' in server/agent code examples, not 'console.log'
Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable
Use inline comments to explain intent ('why'), not syntax ('what')
Do not use suppression comments like '//@ts-ignore', '// eslint-disable', or other code suppressions in documentation examples
Use action-oriented titles (e.g., 'Calling Other Agents' not 'Agent Communication') for documentation pages
Keep feature documentation provider-agnostic where possible; use current model names in code examples and verify they are up to date before publishing
Use 'info' callout type for context and clarifications, 'warning' for gotchas and required setup, 'tip' for optimizations and advanced patterns
Make cross-links context-specific: include why the reader would follow the link (e.g., 'See Streaming Responses for chunked output patterns')
Link to external tools on first mention only; do not re-link on the same page
Replace hollow adjectives (e.g., 'powerful', 'seamless', 'enterprise-grade') with specific benefits; use precise language like 'consistent API', 'type-safe', 'observable', 'faster'
Explicitly mark optional parameters as 'optional' in prose; readers should not need to parse type signatures
Use inline code references to show API shape, config values, or method signatures without imports; use standalone examples for concepts that require copy-pasteable code
Prefer 'Prefersfrom@agentuity/schemafor schemas; show schema-agnostic SDK examples using other StandardSchema libraries (Zod, ArkType, Valibot) across documentation
Use a balance of raw SDK providers and AI SDK providers (openai(),anthropic()) in code examples throughout documentation
Strip boilerplate from code examples; show only the feature being demonstrated
Files:
apps/docs/src/web/content/routes/webrtc.mdx
🪛 LanguageTool
apps/docs/src/web/content/routes/webrtc.mdx
[style] ~399-~399: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...mediated** bidirectional communication. Use SSE for **server-to-clie...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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/reference/api/oauth.mdx`:
- Around line 146-151: Update the OAuthClientSchema's internal field so it
includes a description: locate the `internal` entry in `OAuthClientSchema`
(currently defined as `z.boolean().optional().default(false)`) and add a
`.describe('Whether this client is an internal/system application')` call so the
schema reads with a description and surfaces in the generated API docs.
🪄 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: 0f10b727-cde0-48a4-8825-d563209c414c
📒 Files selected for processing (4)
apps/docs/src/web/content/reference/api/oauth.mdxapps/docs/src/web/content/reference/api/sandboxes.mdxapps/docs/src/web/content/reference/cli/sandbox.mdxapps/docs/src/web/content/services/sandbox/index.mdx
✅ Files skipped from review due to trivial changes (1)
- apps/docs/src/web/content/reference/cli/sandbox.mdx
🚧 Files skipped from review as they are similar to previous changes (2)
- apps/docs/src/web/content/services/sandbox/index.mdx
- apps/docs/src/web/content/reference/api/sandboxes.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). (15)
- GitHub Check: Agentuity Deployment
- GitHub Check: Pack & Upload
- GitHub Check: Postgres SSL Integration Test
- GitHub Check: Build
- GitHub Check: Cloud Deployment Tests
- GitHub Check: Framework Integration Tests (TanStack & Next.js)
- GitHub Check: Queue SDK Tests
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Queue CLI Tests
- GitHub Check: Storage CLI Tests
- GitHub Check: Package Installation & Usage Test
- GitHub Check: Template Integration Tests
- GitHub Check: Sandbox CLI Tests
- GitHub Check: SDK Integration Test Suite
- GitHub Check: Standalone Agent Test
🧰 Additional context used
📓 Path-based instructions (1)
apps/docs/src/web/content/**/*.mdx
📄 CodeRabbit inference engine (apps/docs/src/web/content/AGENTS.md)
apps/docs/src/web/content/**/*.mdx: Write 1-2 sentences of motivation before showing code (context-then-code principle)
Use 'ctx.logger' in server/agent code examples, not 'console.log'
Include imports at the top of standalone code examples to ensure they are copy-pasteable and runnable
Use inline comments to explain intent ('why'), not syntax ('what')
Do not use suppression comments like '//@ts-ignore', '// eslint-disable', or other code suppressions in documentation examples
Use action-oriented titles (e.g., 'Calling Other Agents' not 'Agent Communication') for documentation pages
Keep feature documentation provider-agnostic where possible; use current model names in code examples and verify they are up to date before publishing
Use 'info' callout type for context and clarifications, 'warning' for gotchas and required setup, 'tip' for optimizations and advanced patterns
Make cross-links context-specific: include why the reader would follow the link (e.g., 'See Streaming Responses for chunked output patterns')
Link to external tools on first mention only; do not re-link on the same page
Replace hollow adjectives (e.g., 'powerful', 'seamless', 'enterprise-grade') with specific benefits; use precise language like 'consistent API', 'type-safe', 'observable', 'faster'
Explicitly mark optional parameters as 'optional' in prose; readers should not need to parse type signatures
Use inline code references to show API shape, config values, or method signatures without imports; use standalone examples for concepts that require copy-pasteable code
Prefer 'Prefersfrom@agentuity/schemafor schemas; show schema-agnostic SDK examples using other StandardSchema libraries (Zod, ArkType, Valibot) across documentation
Use a balance of raw SDK providers and AI SDK providers (openai(),anthropic()) in code examples throughout documentation
Strip boilerplate from code examples; show only the feature being demonstrated
Files:
apps/docs/src/web/content/reference/api/oauth.mdx
🔇 Additional comments (3)
apps/docs/src/web/content/reference/api/oauth.mdx (3)
416-421: Same issue as noted above (lines 146-151).Empty description for
client.internalfield. The consolidated fix in the generation script would address this occurrence as well.
593-598: Same issue as noted above (lines 146-151).Empty description for
internalfield. The consolidated fix in the generation script would address this occurrence as well.
859-864: Same issue as noted above (lines 146-151).Empty description for
client.internalfield. The consolidated fix in the generation script would address this occurrence as well.
| { | ||
| "name": "internal", | ||
| "type": "boolean", | ||
| "description": "", | ||
| "required": true | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify how the generation script handles optional fields with defaults
fd -t f 'generate-api-reference' --exec cat {}Repository: agentuity/sdk
Length of output: 14542
🏁 Script executed:
cat packages/core/src/services/oauth/api-reference.tsRepository: agentuity/sdk
Length of output: 14369
🏁 Script executed:
head -100 packages/core/src/services/api-reference.tsRepository: agentuity/sdk
Length of output: 2345
🏁 Script executed:
rg "internal.*boolean" packages/core/src/services/oauth/ -A 2 -B 2Repository: agentuity/sdk
Length of output: 457
🏁 Script executed:
sed -n '80,200p' packages/core/src/services/api-reference.tsRepository: agentuity/sdk
Length of output: 3478
🏁 Script executed:
cat packages/core/src/services/oauth/types.ts | grep -A 30 "OAuthClientListItemSchema"Repository: agentuity/sdk
Length of output: 3776
🏁 Script executed:
cat packages/core/src/services/oauth/types.ts | grep -B 50 "internal: z.boolean" | head -80Repository: agentuity/sdk
Length of output: 862
🏁 Script executed:
rg "\.describe\(" packages/core/src/services/oauth/types.ts -A 1 -B 1 | head -30Repository: agentuity/sdk
Length of output: 966
Add description to the internal field in the schema source.
The internal field in OAuthClientSchema (packages/core/src/services/oauth/types.ts) lacks a .describe() call. Without it, the generated API documentation shows an empty description. The required: true is correct—Zod's .optional().default(false) ensures the field is always present in API responses, making it required.
Add a description like:
internal: z.boolean().optional().default(false).describe('Whether this client is an internal/system application'),This will populate the description in all four response endpoints (lines 146-151, 416-421, 593-598, 859-864 in oauth.mdx).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/src/web/content/reference/api/oauth.mdx` around lines 146 - 151,
Update the OAuthClientSchema's internal field so it includes a description:
locate the `internal` entry in `OAuthClientSchema` (currently defined as
`z.boolean().optional().default(false)`) and add a `.describe('Whether this
client is an internal/system application')` call so the schema reads with a
description and surfaces in the generated API docs.
- Claude Agent SDK and Chat SDK integrations - Web exploration and autonomous research patterns - Link code-runner and scheduled-digest examples - Consistent `:` separators for example links
# Conflicts: # apps/docs/src/web/content/reference/cli/sandbox.mdx
# Conflicts: # apps/docs/src/web/components/docs/nav-data.ts # apps/docs/src/web/content/reference/meta.json
- Add standalone packages page with service access table - Expand SDK reference into 11 sub-pages with fixed heading hierarchy - Add missing sidebar entries for email, webhooks, schedules, tasks - Add streaming responses section to agents reference - Fix vector upsert field name, em-dashes, model names - Regenerate nav-data and routeTree
- Rewrite Reference and CLI index pages with card-based layouts - Create 5 SDK Reference service pages and auth services hub page - Expand thin SDK Reference pages and add cross-links - Reword standalone callouts, unify icons across sections - Add SDK Reference subpage convention to AGENTS.md
- Document sandbox job control and OAuth token management - Add missing route files for new pages - Fix Next Steps format and icon consistency
- Move "When to Use" sections to top of page - Replace sparse checkmark tables with two-column format - Consistent cross-links between WebSocket, SSE, WebRTC - Update stale model name in SSE example
2 participants
Bring together docs changes made across stale or existing branches.
Summary by CodeRabbit
Documentation
Updates
Style
UX