docs: comprehensive documentation audit and fixes#79
Open
zrosenbauer wants to merge 1 commit into
Open
Conversation
Fix 30+ documentation issues across all packages found during a
multi-pass audit comparing docs against actual source code.
Key fixes:
- Type definitions now match source (GenerateResult, StreamResult,
FlowAgentGenerateResult, BaseStreamResult, UsageCost, ModelPricing)
- Messages accessed via result.response.messages, not result.messages
- Agent method signatures use GenerateParams object, not positional args
- model() examples use native IDs (gpt-4.1), not prefixed (openai/gpt-4.1)
- TokenUsage replaced with LanguageModelUsage from AI SDK
- Added reasoning field to all pricing/cost tables and formulas
- Cost formula reflects noCacheTokens/textTokens detail-field preference
- Fixed error messages to match actual thrown strings
- Invalid model IDs replaced with real catalog entries
- onFinish hooks use { input, result, duration } not { output }
- Removed duplicate docs, replaced with redirects to canonical files
- Added missing docs: runtime API, @funkai/config, @funkai/cli
- Fixed broken links, dead README links, wrong package names
- Standardized API key setup across all examples
- Updated TypeScript version references to ^6.0.3
Co-Authored-By: Claude <noreply@anthropic.com>
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis is a comprehensive documentation update refactoring the API surfaces for Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 13
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (9)
packages/prompts/docs/cli.md (1)
1-1:⚠️ Potential issue | 🟡 MinorResolve oxfmt formatting failure.
The pipeline reports this file has formatting issues. Run
pnpm formatfrom the repository root to fix.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/prompts/docs/cli.md` at line 1, This file fails oxfmt formatting; open the document containing the "# CLI" header and run the repository formatter (pnpm format) from the repo root to apply oxfmt rules, or manually fix whitespace/line-ending/markdown formatting to match the project's formatter, then stage and commit the updated file so the pipeline passes.contributing/concepts/tech-stack.md (1)
1-1:⚠️ Potential issue | 🟡 MinorResolve oxfmt formatting failure.
The pipeline reports this file has formatting issues. Run
pnpm formatfrom the repository root to fix.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@contributing/concepts/tech-stack.md` at line 1, The "Tech Stack" markdown file has oxfmt formatting issues; run the formatter from the repo root (pnpm format) to fix formatting in contributing/concepts/tech-stack.md (the file containing the "Tech Stack" header), then review the changed file, stage and commit the formatted file so the CI formatting check passes.contributing/concepts/architecture.md (1)
1-1:⚠️ Potential issue | 🟠 MajorCI blocker: xfmt check is failing for this file.
Please run the repository formatter for
contributing/concepts/architecture.md; the current content does not pass the formatting gate and will block merge.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@contributing/concepts/architecture.md` at line 1, The file contributing/concepts/architecture.md (the "Architecture" document) fails the xfmt formatting check; run the repository formatter (xfmt) on that file to apply the standard markdown styling so it passes CI, then re-run the xfmt/lint check to confirm; ensure the header "Architecture" and surrounding markdown follow the project's formatter rules before pushing the changes.packages/prompts/docs/codegen.md (1)
1-1:⚠️ Potential issue | 🟠 MajorCI blocker: xfmt check is failing for this file.
Formatting must be fixed for
packages/prompts/docs/codegen.mdbefore merge.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/prompts/docs/codegen.md` at line 1, Run the project's formatter (xfmt) on the Markdown file that contains the "# Code Generation & Library" heading and commit the updated file; ensure the heading uses a single '#' followed by one space, remove any trailing whitespace, and make sure the file ends with a newline so the xfmt check passes.packages/prompts/docs/library/overview.md (1)
1-1:⚠️ Potential issue | 🟠 MajorCI blocker: xfmt check is failing for this file.
Formatting issues in
packages/prompts/docs/library/overview.mdmust be resolved for CI to pass.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/prompts/docs/library/overview.md` at line 1, The markdown file containing the heading "# Library API" is failing the xfmt check; run the project's formatter (xfmt) on that file to auto-fix formatting, or manually ensure the header and surrounding text follow the formatter rules (remove trailing spaces, ensure a single blank line after the header, consistent line endings, and a newline at EOF), save the file and commit the formatted changes so CI passes.packages/agents/docs/provider/models.md (1)
19-27:⚠️ Potential issue | 🟡 MinorPricing field name inconsistency.
The table documents the field as
prompt(line 20), but the code examples usepricing.input(lines 36, 61). These should match.📋 Proposed fix to align table with code examples
| Field | Type | Description | | ------------------- | -------- | ------------------------------------- | -| `prompt` | `number` | USD per input token | +| `input` | `number` | USD per input token | +| `output` | `number` | USD per output token | -| `completion` | `number` | USD per output token | | `inputCacheRead` | `number` | USD per cached input token (optional) | | `inputCacheWrite` | `number` | USD per cached input write (optional) |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/agents/docs/provider/models.md` around lines 19 - 27, The table uses top-level names like `prompt`/`completion` but the examples use nested `pricing.*` fields (e.g., `pricing.input`, `pricing.completion`); update the table rows to the same names used in the examples — replace `prompt` with `pricing.input`, `completion` with `pricing.completion`, and likewise prefix `inputCacheRead`, `inputCacheWrite`, `webSearch`, `internalReasoning`, and `image` with `pricing.` so the documented field names match the code examples (`pricing.input`, `pricing.completion`, `pricing.inputCacheRead`, etc.).packages/agents/docs/advanced/streaming.md (1)
1-240:⚠️ Potential issue | 🟠 MajorCI is currently blocked by formatting for this file.
xfmtis failing for this file in CI and must be fixed before merge.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/agents/docs/advanced/streaming.md` around lines 1 - 240, CI failure is due to formatting errors in this markdown (e.g., around the "Streaming" header, the mermaid block, and code fences referencing StreamResult/fullStream); run the project's formatter (xfmt) on this file, fix any reported issues (trailing spaces, inconsistent indentation in code blocks/mermaid, and fence/backtick mismatches), verify the doc compiles/looks correct, and commit the formatted file.packages/models/docs/cost/overview.md (1)
1-126:⚠️ Potential issue | 🟠 MajorCI is currently blocked by formatting for this file.
xfmtis failing for this file in CI and needs to be resolved before release.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/models/docs/cost/overview.md` around lines 1 - 126, The CI failure is due to markdown formatting rules for this docs file; run the project's markdown formatter (xfmt) on this file, fix any reported issues (unclosed or misfenced code blocks, stray backticks, trailing spaces, inconsistent table separators) and reformat the code blocks and tables around the calculateCost(), LanguageModelUsage, ModelPricing, and UsageCost sections so they comply with xfmt, then re-run xfmt to ensure the file passes linting.packages/agents/docs/core/step.md (1)
1-310:⚠️ Potential issue | 🟠 MajorCI is currently blocked by formatting for this file.
xfmtis failing for this file in CI and should be fixed before merging.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/agents/docs/core/step.md` around lines 1 - 310, The file's formatting violates the project's xfmt rules and CI is failing; run xfmt on the "StepBuilder" docs (the markdown containing the "$ StepBuilder" heading and the "FlowStepResult" code block and all ````ts```` fences), fix any spacing/indentation/blank-line issues reported (ensure code fences use ```ts, headings and lists have proper blank lines, and there are no trailing spaces), then re-run xfmt and commit the formatted file so CI passes.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@contributing/concepts/tech-stack.md`:
- Line 11: The docs list TypeScript as "^6.0.3" in
contributing/concepts/tech-stack.md but the lockfile shows typescript@5.9.3; fix
the mismatch by either updating the project's dependency to a 6.x TypeScript
(bump package.json and regenerate pnpm-lock.yaml and any build configs) or by
reverting the documentation entry in tech-stack.md to "^5.9.x" (or "5.9.3") to
reflect the actual installed version; update the single line containing
"[TypeScript](https://www.typescriptlang.org) | Type system | ^6.0.3" to the
chosen version string so docs and lockfile agree.
In `@packages/agents/docs/advanced/streaming.md`:
- Around line 59-60: The docs currently reference a non-existent textStream
property; remove all mentions of textStream from the interface example and the
field table in the streaming.md doc so the documentation matches the actual
BaseStreamResult/StreamResult contract (which only exposes usage, finishReason
and fullStream). Update any surrounding wording to reference fullStream
(AsyncIterableStream<StreamPart>) instead and verify no example code or table
rows still list textStream.
In `@packages/agents/docs/core/flow-agent.md`:
- Around line 79-84: The documentation type for BaseStreamResult is incorrect:
change the documented types for usage and finishReason from PromiseLike to
Promise to match the actual AI SDK/StreamTextResult types; update the
BaseStreamResult declaration so that output remains PromiseLike<TOutput> but
usage: Promise<LanguageModelUsage> and finishReason: Promise<FinishReason>
(matching StreamTextResult) to keep the docs consistent with the actual types.
In `@packages/agents/docs/core/types.md`:
- Line 89: Update the documentation table entry that currently lists the `usage`
type as `TokenUsage` so it matches the renamed type `LanguageModelUsage`;
replace the `TokenUsage` reference with `LanguageModelUsage` in the table row
for `usage` to maintain consistency with the rest of the doc and the renamed
type.
In `@packages/agents/docs/guides/cost-aware-agents.md`:
- Around line 58-60: The top-level snippet uses "if (!modelDef) { return; }"
which is invalid in a module; change the guard in the example to throw an Error
instead (e.g., inside the same if checking modelDef) so the code remains valid
when copied; update the example where "modelDef" is validated (the if block
referencing modelDef) to throw a descriptive error (e.g., throw new Error("model
definition missing") ) rather than returning.
In `@packages/agents/docs/step-builder.md`:
- Line 82: Run the markdown formatter (xfmt) on the affected file to normalize
formatting and commit the result; specifically fix the table row containing the
`stream` column (the line with `stream`, `boolean`, and the text "Use
`agent.stream()` instead of `agent.generate()` (default: `false`)") so the table
alignment and markdown normalization match the project's formatter output, then
stage and push the formatted file to unblock CI.
In `@packages/models/docs/catalog.md`:
- Line 76: The docs table in catalog.md lists a non-existent property
`reasoning` for ModelPricing; update the documentation to match the TypeScript
model by removing the `reasoning` row (or, if the intent was to expose a pricing
field, add `reasoning?: number` to the ModelPricing type in types.ts and update
any related logic). Ensure the change references the ModelPricing type and the
catalog.md table so the API surface in docs and code stays consistent.
In `@packages/models/docs/catalog/overview.md`:
- Line 78: The docs list a ModelPricing.reasoning field that doesn't exist in
the actual type; either add the optional field to the ModelPricing type or
remove it from the docs. Update the ModelPricing definition (add reasoning?:
number | undefined alongside input, output, cacheRead, cacheWrite) in the type
declarations where ModelPricing is defined, or delete the `reasoning` row from
the docs to keep them consistent.
In `@packages/models/docs/provider-resolution.md`:
- Line 203: CI is failing due to formatting in
packages/models/docs/provider-resolution.md; run the project's formatter (xfmt)
on that file (or on the repo) to reformat the doc so the table and inline code
are properly formatted, then stage and commit the reformatted file; look for the
table row containing the message `Invalid model ID "<id>": expected
"provider/model" format (e.g. "openai/gpt-4.1")` and ensure pipes, backticks and
spacing conform to xfmt rules before committing.
In `@packages/models/docs/provider/configuration.md`:
- Line 70: The markdown in configuration.md is failing the xfmt check; run the
project formatter (e.g., the repository's format script or xfmt) against the
file and commit the resulting changes so the table row containing the text
'Invalid model ID "<id>": expected "provider/model" format (e.g.
"openai/gpt-4.1")' is properly formatted and the CI xfmt check passes.
In `@packages/prompts/docs/codegen.md`:
- Line 96: The documentation refers to a shared instance as `engine` but the
actual exported/runtime symbol is `liquidEngine`; update the text to use
`liquidEngine` everywhere (or change the exported identifier to `engine` if you
prefer that name) so the documented symbol matches the real runtime symbol
(reference `liquidEngine` in this file and any examples that mention the shared
instance, and verify exports/README mention the same identifier).
In `@packages/prompts/docs/library/overview.md`:
- Line 28: The docs erroneously refer to a shared "engine" instance but the
exported symbol is named "liquidEngine"; update the text to consistently use
"liquidEngine" (e.g., replace "engine" with "liquidEngine" where describing
configuration options like ownPropertyOnly/strictFilters/strictVariables and
parseAndRenderSync) so examples and documentation match the actual exported
identifier.
In `@packages/prompts/docs/library/runtime-api.md`:
- Line 1: The file packages/prompts/docs/library/runtime-api.md is failing the
xfmt CI check due to formatting issues; run the project's xfmt formatter (or the
configured markdown formatter) on runtime-api.md and apply its automatic fixes,
ensuring the top-level heading "Runtime Prompt Construction API" and the rest of
the document are normalized to the repository's markdown style (line endings,
trailing whitespace, consistent heading/paragraph spacing); re-run xfmt locally
and commit the formatted file so the CI check passes.
---
Outside diff comments:
In `@contributing/concepts/architecture.md`:
- Line 1: The file contributing/concepts/architecture.md (the "Architecture"
document) fails the xfmt formatting check; run the repository formatter (xfmt)
on that file to apply the standard markdown styling so it passes CI, then re-run
the xfmt/lint check to confirm; ensure the header "Architecture" and surrounding
markdown follow the project's formatter rules before pushing the changes.
In `@contributing/concepts/tech-stack.md`:
- Line 1: The "Tech Stack" markdown file has oxfmt formatting issues; run the
formatter from the repo root (pnpm format) to fix formatting in
contributing/concepts/tech-stack.md (the file containing the "Tech Stack"
header), then review the changed file, stage and commit the formatted file so
the CI formatting check passes.
In `@packages/agents/docs/advanced/streaming.md`:
- Around line 1-240: CI failure is due to formatting errors in this markdown
(e.g., around the "Streaming" header, the mermaid block, and code fences
referencing StreamResult/fullStream); run the project's formatter (xfmt) on this
file, fix any reported issues (trailing spaces, inconsistent indentation in code
blocks/mermaid, and fence/backtick mismatches), verify the doc compiles/looks
correct, and commit the formatted file.
In `@packages/agents/docs/core/step.md`:
- Around line 1-310: The file's formatting violates the project's xfmt rules and
CI is failing; run xfmt on the "StepBuilder" docs (the markdown containing the
"$ StepBuilder" heading and the "FlowStepResult" code block and all ````ts````
fences), fix any spacing/indentation/blank-line issues reported (ensure code
fences use ```ts, headings and lists have proper blank lines, and there are no
trailing spaces), then re-run xfmt and commit the formatted file so CI passes.
In `@packages/agents/docs/provider/models.md`:
- Around line 19-27: The table uses top-level names like `prompt`/`completion`
but the examples use nested `pricing.*` fields (e.g., `pricing.input`,
`pricing.completion`); update the table rows to the same names used in the
examples — replace `prompt` with `pricing.input`, `completion` with
`pricing.completion`, and likewise prefix `inputCacheRead`, `inputCacheWrite`,
`webSearch`, `internalReasoning`, and `image` with `pricing.` so the documented
field names match the code examples (`pricing.input`, `pricing.completion`,
`pricing.inputCacheRead`, etc.).
In `@packages/models/docs/cost/overview.md`:
- Around line 1-126: The CI failure is due to markdown formatting rules for this
docs file; run the project's markdown formatter (xfmt) on this file, fix any
reported issues (unclosed or misfenced code blocks, stray backticks, trailing
spaces, inconsistent table separators) and reformat the code blocks and tables
around the calculateCost(), LanguageModelUsage, ModelPricing, and UsageCost
sections so they comply with xfmt, then re-run xfmt to ensure the file passes
linting.
In `@packages/prompts/docs/cli.md`:
- Line 1: This file fails oxfmt formatting; open the document containing the "#
CLI" header and run the repository formatter (pnpm format) from the repo root to
apply oxfmt rules, or manually fix whitespace/line-ending/markdown formatting to
match the project's formatter, then stage and commit the updated file so the
pipeline passes.
In `@packages/prompts/docs/codegen.md`:
- Line 1: Run the project's formatter (xfmt) on the Markdown file that contains
the "# Code Generation & Library" heading and commit the updated file; ensure
the heading uses a single '#' followed by one space, remove any trailing
whitespace, and make sure the file ends with a newline so the xfmt check passes.
In `@packages/prompts/docs/library/overview.md`:
- Line 1: The markdown file containing the heading "# Library API" is failing
the xfmt check; run the project's formatter (xfmt) on that file to auto-fix
formatting, or manually ensure the header and surrounding text follow the
formatter rules (remove trailing spaces, ensure a single blank line after the
header, consistent line endings, and a newline at EOF), save the file and commit
the formatted changes so CI passes.
🪄 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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 983192ab-38a8-486d-a8d7-0a5eb527255f
📒 Files selected for processing (57)
.gitignoreREADME.mdcontributing/concepts/architecture.mdcontributing/concepts/tech-stack.mdcontributing/guides/getting-started.mdcontributing/standards/git-commits.mdexamples/basic-agent/README.mdexamples/flow-agent/README.mdexamples/prompts-basic/README.mdexamples/prompts-subagents/README.mdexamples/realworld-cli/README.mdexamples/streaming/README.mdpackages/agents/docs/advanced/streaming.mdpackages/agents/docs/core/agent.mdpackages/agents/docs/core/context.mdpackages/agents/docs/core/flow-agent.mdpackages/agents/docs/core/hooks.mdpackages/agents/docs/core/overview.mdpackages/agents/docs/core/step.mdpackages/agents/docs/core/tools.mdpackages/agents/docs/core/tracing.mdpackages/agents/docs/core/types.mdpackages/agents/docs/cost-tracking.mdpackages/agents/docs/create-agent.mdpackages/agents/docs/create-flow-agent.mdpackages/agents/docs/guides/cost-aware-agents.mdpackages/agents/docs/guides/create-agent.mdpackages/agents/docs/guides/create-flow-agent.mdpackages/agents/docs/guides/create-tool.mdpackages/agents/docs/guides/test-agents.mdpackages/agents/docs/overview.mdpackages/agents/docs/provider/models.mdpackages/agents/docs/provider/overview.mdpackages/agents/docs/step-builder.mdpackages/agents/docs/streaming.mdpackages/agents/docs/test-agents.mdpackages/agents/docs/troubleshooting.mdpackages/models/docs/catalog.mdpackages/models/docs/catalog/overview.mdpackages/models/docs/cost-tracking.mdpackages/models/docs/cost/overview.mdpackages/models/docs/guides/setup-resolver.mdpackages/models/docs/guides/track-costs.mdpackages/models/docs/overview.mdpackages/models/docs/provider-resolution.mdpackages/models/docs/provider/configuration.mdpackages/models/docs/provider/overview.mdpackages/models/docs/troubleshooting.mdpackages/prompts/README.mdpackages/prompts/docs/cli.mdpackages/prompts/docs/cli/commands.mdpackages/prompts/docs/cli/overview.mdpackages/prompts/docs/codegen.mdpackages/prompts/docs/codegen/overview.mdpackages/prompts/docs/file-format/overview.mdpackages/prompts/docs/library/overview.mdpackages/prompts/docs/library/runtime-api.md
| | Tool | Purpose | Version | Documentation | | ||
| | -------------------------------------------- | ---------------------- | ------- | -------------------------------------------------------------------------------------------- | | ||
| | [TypeScript](https://www.typescriptlang.org) | Type system | ^5.9 | [Handbook](https://www.typescriptlang.org/docs/) | | ||
| | [TypeScript](https://www.typescriptlang.org) | Type system | ^6.0.3 | [Handbook](https://www.typescriptlang.org/docs/) | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the actual TypeScript version installed and used across the monorepo
echo "=== TypeScript version in pnpm-lock.yaml ==="
rg -n "typescript@" pnpm-lock.yaml | head -5
echo -e "\n=== TypeScript version in package.json files ==="
fd package.json --exec jq -r 'select(.devDependencies.typescript or .dependencies.typescript) | {file: input_filename, version: (.devDependencies.typescript // .dependencies.typescript)}' {} \;
echo -e "\n=== TypeScript version constraint in root package.json ==="
jq -r '.devDependencies.typescript // .dependencies.typescript // "not found"' package.jsonRepository: joggrdocs/funkai
Length of output: 1458
🏁 Script executed:
cat -n contributing/concepts/tech-stack.md | sed -n '1,160p'Repository: joggrdocs/funkai
Length of output: 11742
TypeScript version mismatch between documentation and actual lockfile.
Lines 11 and 141 claim TypeScript ^6.0.3 (minimum 6.0.x), but pnpm-lock.yaml shows typescript@5.9.3 is installed. The documented standard is TypeScript 5.9. Either upgrade the dependency to match the documented requirement, or revert the documentation to ^5.9.x.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@contributing/concepts/tech-stack.md` at line 11, The docs list TypeScript as
"^6.0.3" in contributing/concepts/tech-stack.md but the lockfile shows
typescript@5.9.3; fix the mismatch by either updating the project's dependency
to a 6.x TypeScript (bump package.json and regenerate pnpm-lock.yaml and any
build configs) or by reverting the documentation entry in tech-stack.md to
"^5.9.x" (or "5.9.3") to reflect the actual installed version; update the single
line containing "[TypeScript](https://www.typescriptlang.org) | Type system |
^6.0.3" to the chosen version string so docs and lockfile agree.
Comment on lines
+59
to
+60
| textStream: AsyncIterableStream<string>; // live text deltas | ||
| fullStream: AsyncIterableStream<StreamPart>; // all stream parts (text, tool calls, etc.) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify docs claim `textStream` and source type does not define it.
rg -n 'textStream|interface StreamResult|BaseStreamResult' packages/agents/docs/advanced/streaming.md packages/agents/src/core/agents/types.ts -C2Repository: joggrdocs/funkai
Length of output: 2562
Remove textStream from documentation—it is not exposed in the StreamResult/BaseStreamResult type contract.
The docs claim textStream at lines 59–60 and in the table at line 67, but the source BaseStreamResult type explicitly picks only "usage" | "finishReason" | "fullStream". Users following the docs will attempt to access a property that does not exist.
Fix
Remove textStream from the interface documentation and the field table:
interface StreamResult<TOutput = string> {
output: PromiseLike<TOutput>; // resolves after stream completes
usage: Promise<LanguageModelUsage>; // resolves after stream completes
finishReason: Promise<string>; // resolves after stream completes
- textStream: AsyncIterableStream<string>; // live text deltas
fullStream: AsyncIterableStream<StreamPart>; // all stream parts (text, tool calls, etc.)
response: Promise<Response>; // resolves after stream completes (includes messages)
}-| `textStream` | `AsyncIterableStream<string>` | Immediately |
| `fullStream` | `AsyncIterableStream<StreamPart>` | Immediately |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/agents/docs/advanced/streaming.md` around lines 59 - 60, The docs
currently reference a non-existent textStream property; remove all mentions of
textStream from the interface example and the field table in the streaming.md
doc so the documentation matches the actual BaseStreamResult/StreamResult
contract (which only exposes usage, finishReason and fullStream). Update any
surrounding wording to reference fullStream (AsyncIterableStream<StreamPart>)
instead and verify no example code or table rows still list textStream.
Comment on lines
+79
to
84
| interface BaseStreamResult<TOutput> { | ||
| output: PromiseLike<TOutput>; // resolves after stream completes | ||
| usage: PromiseLike<LanguageModelUsage>; // resolves after stream completes | ||
| finishReason: PromiseLike<FinishReason>; // resolves after stream completes | ||
| fullStream: AsyncIterableStream<StreamPart>; | ||
| } |
There was a problem hiding this comment.
usage and finishReason should be Promise, not PromiseLike.
Lines 81-82 document these as PromiseLike, but the source code at packages/agents/src/core/agents/types.ts shows BaseStreamResult picks usage and finishReason directly from the AI SDK's StreamTextResult, where they are Promise types. Only output is explicitly PromiseLike<TOutput>.
📝 Proposed fix
interface BaseStreamResult<TOutput> {
output: PromiseLike<TOutput>; // resolves after stream completes
- usage: PromiseLike<LanguageModelUsage>; // resolves after stream completes
- finishReason: PromiseLike<FinishReason>; // resolves after stream completes
+ usage: Promise<LanguageModelUsage>; // resolves after stream completes
+ finishReason: Promise<FinishReason>; // resolves after stream completes
fullStream: AsyncIterableStream<StreamPart>;
}📝 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.
Suggested change
| interface BaseStreamResult<TOutput> { | |
| output: PromiseLike<TOutput>; // resolves after stream completes | |
| usage: PromiseLike<LanguageModelUsage>; // resolves after stream completes | |
| finishReason: PromiseLike<FinishReason>; // resolves after stream completes | |
| fullStream: AsyncIterableStream<StreamPart>; | |
| } | |
| interface BaseStreamResult<TOutput> { | |
| output: PromiseLike<TOutput>; // resolves after stream completes | |
| usage: Promise<LanguageModelUsage>; // resolves after stream completes | |
| finishReason: Promise<FinishReason>; // resolves after stream completes | |
| fullStream: AsyncIterableStream<StreamPart>; | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/agents/docs/core/flow-agent.md` around lines 79 - 84, The
documentation type for BaseStreamResult is incorrect: change the documented
types for usage and finishReason from PromiseLike to Promise to match the actual
AI SDK/StreamTextResult types; update the BaseStreamResult declaration so that
output remains PromiseLike<TOutput> but usage: Promise<LanguageModelUsage> and
finishReason: Promise<FinishReason> (matching StreamTextResult) to keep the docs
consistent with the actual types.
| | -------------- | ------------ | ------------------------------------------------------------------ | | ||
| | `output` | `TOutput` | The generation output (typed based on `Output` strategy) | | ||
| | `messages` | `Message[]` | Full message history including tool calls | | ||
| | `usage` | `TokenUsage` | Aggregated token usage across all tool-loop steps | |
There was a problem hiding this comment.
Inconsistent type name: should be LanguageModelUsage.
Line 89 uses TokenUsage but line 122 correctly uses LanguageModelUsage. The PR renamed this type throughout. Update to match.
📝 Proposed fix
-| `usage` | `TokenUsage` | Aggregated token usage across all tool-loop steps |
+| `usage` | `LanguageModelUsage` | Aggregated token usage across all tool-loop steps |📝 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.
Suggested change
| | `usage` | `TokenUsage` | Aggregated token usage across all tool-loop steps | | |
| | `usage` | `LanguageModelUsage` | Aggregated token usage across all tool-loop steps | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/agents/docs/core/types.md` at line 89, Update the documentation
table entry that currently lists the `usage` type as `TokenUsage` so it matches
the renamed type `LanguageModelUsage`; replace the `TokenUsage` reference with
`LanguageModelUsage` in the table row for `usage` to maintain consistency with
the rest of the doc and the renamed type.
Comment on lines
+58
to
+60
| if (!modelDef) { | ||
| return; | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the problematic pattern exists in docs examples.
rg -n -C2 'if \(!modelDef\) \{|^\s*return;\s*$' packages/agents/docs/guides/cost-aware-agents.mdRepository: joggrdocs/funkai
Length of output: 408
🏁 Script executed:
sed -n '50,75p' packages/agents/docs/guides/cost-aware-agents.mdRepository: joggrdocs/funkai
Length of output: 838
🏁 Script executed:
sed -n '45,95p' packages/agents/docs/guides/cost-aware-agents.mdRepository: joggrdocs/funkai
Length of output: 1499
🏁 Script executed:
sed -n '35,50p' packages/agents/docs/guides/cost-aware-agents.mdRepository: joggrdocs/funkai
Length of output: 495
Module-level return; in code example is a syntax error.
The code snippet at lines 58–60 uses return; at the top level of a TypeScript module (inside an if block, not inside a function). This is invalid and will throw SyntaxError: Illegal return statement if copied. The corrected examples later in the document use throw new Error() instead; align this example with that pattern.
Proposed fix
if (!modelDef) {
- return;
+ throw new Error("Unknown model: gpt-4.1");
}📝 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.
Suggested change
| if (!modelDef) { | |
| return; | |
| } | |
| if (!modelDef) { | |
| throw new Error("Unknown model: gpt-4.1"); | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/agents/docs/guides/cost-aware-agents.md` around lines 58 - 60, The
top-level snippet uses "if (!modelDef) { return; }" which is invalid in a
module; change the guard in the example to throw an Error instead (e.g., inside
the same if checking modelDef) so the code remains valid when copied; update the
example where "modelDef" is validated (the if block referencing modelDef) to
throw a descriptive error (e.g., throw new Error("model definition missing") )
rather than returning.
| | --------------- | ---------------------------------------------------------------- | | ||
| | Empty model ID | `Cannot resolve model: model ID is empty` | | ||
| | No prefix | `Cannot resolve model "<id>": no provider prefix` | | ||
| | No prefix | `Invalid model ID "<id>": expected "provider/model" format (e.g. "openai/gpt-4.1")` | |
There was a problem hiding this comment.
CI blocker: formatting check is failing for this file.
GitHub Actions reports xfmt failure here. Reformat and commit to restore passing CI.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/models/docs/provider-resolution.md` at line 203, CI is failing due
to formatting in packages/models/docs/provider-resolution.md; run the project's
formatter (xfmt) on that file (or on the repo) to reformat the doc so the table
and inline code are properly formatted, then stage and commit the reformatted
file; look for the table row containing the message `Invalid model ID "<id>":
expected "provider/model" format (e.g. "openai/gpt-4.1")` and ensure pipes,
backticks and spacing conform to xfmt rules before committing.
| | --------------- | ---------------------------------------------------------------- | | ||
| | Empty model ID | `Cannot resolve model: model ID is empty` | | ||
| | No prefix | `Cannot resolve model "<id>": no provider prefix` | | ||
| | No prefix | `Invalid model ID "<id>": expected "provider/model" format (e.g. "openai/gpt-4.1")` | |
There was a problem hiding this comment.
CI blocker: markdown formatting is failing in this file.
The xfmt check is failing in CI for this document. Please run the project formatter and commit the result.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/models/docs/provider/configuration.md` at line 70, The markdown in
configuration.md is failing the xfmt check; run the project formatter (e.g., the
repository's format script or xfmt) against the file and commit the resulting
changes so the table row containing the text 'Invalid model ID "<id>": expected
"provider/model" format (e.g. "openai/gpt-4.1")' is properly formatted and the
CI xfmt check passes.
| ### Engine | ||
|
|
||
| The shared `engine` instance is configured with `ownPropertyOnly: true` and `strictFilters: true` for security. No filesystem access -- templates are rendered from strings via `parseAndRenderSync`. | ||
| The shared `engine` instance is configured with `ownPropertyOnly: true`, `strictFilters: true`, and `strictVariables: true` for security. No filesystem access -- templates are rendered from strings via `parseAndRenderSync`. |
There was a problem hiding this comment.
Use the correct runtime symbol name (liquidEngine).
Line 96 documents a shared engine instance, but the documented/exported identifier in this page is liquidEngine (Line 87). Please align the identifier to avoid API confusion.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/prompts/docs/codegen.md` at line 96, The documentation refers to a
shared instance as `engine` but the actual exported/runtime symbol is
`liquidEngine`; update the text to use `liquidEngine` everywhere (or change the
exported identifier to `engine` if you prefer that name) so the documented
symbol matches the real runtime symbol (reference `liquidEngine` in this file
and any examples that mention the shared instance, and verify exports/README
mention the same identifier).
| ## Engine | ||
|
|
||
| The shared `engine` instance is configured with `ownPropertyOnly: true` and `strictFilters: true` for security. No filesystem access -- templates are rendered from strings via `parseAndRenderSync`. | ||
| The shared `engine` instance is configured with `ownPropertyOnly: true`, `strictFilters: true`, and `strictVariables: true` for security. No filesystem access -- templates are rendered from strings via `parseAndRenderSync`. |
There was a problem hiding this comment.
Use liquidEngine consistently in engine docs.
Line 28 references a shared engine instance, but the documented export is liquidEngine (Line 9). This should be consistent to prevent incorrect usage.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/prompts/docs/library/overview.md` at line 28, The docs erroneously
refer to a shared "engine" instance but the exported symbol is named
"liquidEngine"; update the text to consistently use "liquidEngine" (e.g.,
replace "engine" with "liquidEngine" where describing configuration options like
ownPropertyOnly/strictFilters/strictVariables and parseAndRenderSync) so
examples and documentation match the actual exported identifier.
| @@ -0,0 +1,236 @@ | |||
| # Runtime Prompt Construction API | |||
There was a problem hiding this comment.
CI blocker: xfmt check is failing for this file.
packages/prompts/docs/library/runtime-api.md needs formatting fixes to pass CI.
🧰 Tools
🪛 GitHub Actions: CI
[error] 1-1: xfmt formatting check failed for this file (listed as having format issues by oxfmt).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/prompts/docs/library/runtime-api.md` at line 1, The file
packages/prompts/docs/library/runtime-api.md is failing the xfmt CI check due to
formatting issues; run the project's xfmt formatter (or the configured markdown
formatter) on runtime-api.md and apply its automatic fixes, ensuring the
top-level heading "Runtime Prompt Construction API" and the rest of the document
are normalized to the repository's markdown style (line endings, trailing
whitespace, consistent heading/paragraph spacing); re-run xfmt locally and
commit the formatted file so the CI check passes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@funkai/agents,@funkai/models, and@funkai/promptscreatePrompt(),createPromptGroup(),createPromptRegistry()Types & APIs
GenerateResult,StreamResult,FlowAgentGenerateResult,BaseStreamResultnow match source types exactlyresult.response.messages(not flatresult.messages)GenerateParamsobject (not positional args)TokenUsage→LanguageModelUsagefrom AI SDKmodel()examples use native IDs (gpt-4.1), not prefixed (openai/gpt-4.1)reasoningfield to all pricing/cost tables and formulasnoCacheTokens/textTokensdetail-field preferenceonFinishhooks use{ input, result, duration }(not{ output })Structural
@funkai/config,@funkai/cliin architecture@joggr/agent-sdk→@funkai/agents)^6.0.3Test plan
find . -name '*.md' | xargs grep -l '\[.*\](.*)')packages/agents/src/core/agents/types.tspackages/prompts/docs/library/runtime-api.mdaccurately reflects exportscli/overview.md,codegen/overview.md,file-format/overview.md) point to correct canonical docs