docs(harness): sharpen overview and session pages#18151
Merged
Conversation
Reframe the Harness overview so it leads with what an agent harness is (a runtime that wraps a model) versus the framework you build an agent from. Make the capabilities outcome-driven, position the Harness as an opinionated default for collaborative sessions instead of implying the Agent class is only for one-shot calls, and add missing reference links (model router, signals, events, observational memory). On the Session page, link the first mention to the Session reference and replace the Harness-vs-Session comparison with a high-level description of the Session's scope of responsibilities. Co-Authored-By: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
|
Superagent didn't find any vulnerabilities or security issues in this PR. |
github-actions
Bot
added
the
Documentation
Contributor
PR triageLinked issue check skipped for core contributor @abhiaiyer91. PR complexity score
Applied label: Changed test gateNo changed test files were detected. Label: |
Contributor
|
Warning Review limit reached
More reviews will be available in 24 minutes and 5 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
WalkthroughDocumentation-only update to three Harness MDX pages. The overview replaces the session-controller framing and application table with capability bullets and Agent-vs-Harness guidance. The modes page adds constraint/startup rules and clarifies mode catalog vs. active mode access. The session page removes the comparison table in favor of a "What the Session tracks" breakdown and expands the Follow-ups and Display state sections with ChangesHarness & Session documentation updates
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Group the Session's sub-objects into four phases (where the conversation lives, how the agent behaves, what's happening now, what you store and render) with anchor links so readers can orient before the detailed sections. Add context to the Follow-ups section, fold the Harness-performs / Session-reads split into one sentence, and refresh the page description.
Modes page: replace 'When to use modes' with a 'Modes are required' section that explains what a mode is (instructions, tools, model), states that the modes array is required and a Harness needs at least one, and notes how the default mode is chosen. Session page: replace the hand-wavy 'coalesced' description of display state with a concrete explanation — it's a reducer-maintained snapshot that folds every harness event into one HarnessDisplayState object, listing the fields it carries and the recommended subscribe-and-render pattern.
Drop the standalone heading and explain that modes are required as part of the opening explanation of what modes are.
Introduce the query methods before the code block, noting the Harness owns the mode catalog and the Session tracks the active mode.
Fold the threads-vs-state guidance into the intro prose instead of a standalone 'When to use' section.
Resource IDs: stop showing the runtime harness.setResourceId() mutation (ambiguous in a multi-session host) and present resourceId as constructor config read back through session.identity. Update the Session page Identity section to match. Drop the standalone 'When to use' headings from tool-approvals and subagents, folding the guidance into each page's intro.
Explain what a thread and state each are and why they matter before the API examples: a thread is the persistent message history, state is the structured shared data alongside it, and both survive mode switches, model changes, and restarts. Add lead paragraphs to the Threads and State sections and remove the duplicated intro definition.
Explain that a subagent's description drives when the parent delegates and its instructions keep the child in scope, so both should be clear and narrow. Note that narrow scoping plus allowedWorkspaceTools keeps routing predictable and avoids over-delegation.
Remove the 'instructions: ... // Ignored in forked mode' line from the forked subagent example. Showing a field that does nothing in this example is confusing; the Forked mode semantics list already documents that the definition's instructions are ignored.
Lead with the use case: forks reuse the parent agent and a clone of the parent thread so the subagent gets full conversation context and an identical prompt prefix (prompt-cache reuse), which is the point of forking. Clarify that the definition's instructions/tools/model are ignored in a fork (only description matters), and fix the incorrect claim that the parent maxSteps applies — forked runs use a fixed step budget, not the parent's.
Remove the sentence describing how the startup mode is chosen (metadata.default / defaultModeId / first mode) — too in the weeds for the intro.
Remove the 'line between a framework and a harness' sentence; fold the lifecycle/context/outside-world detail into the harness definition.
Replace the 'agent harness is the runtime' framing with the original session-controller opening paragraph.
A Session has one active thread at a time but can list, switch between, and clone many threads, so it is not scoped to a single conversation. Reframe the intro and 'What the Session tracks' around a single user's live state scoped by identity, and correct the multi-session note to 'many users' rather than 'many conversations'.
Replace the field-by-field HarnessDisplayState list with a prose summary of what the snapshot captures; the reference note already links the full field list.
LekoArts
approved these changes
Jun 18, 2026
wardpeet
pushed a commit
that referenced
this pull request
Jun 19, 2026
## Summary
Improves the Harness documentation so it explains what a harness is and
what it's for before diving into APIs.
### Harness overview
- Lead with a clear definition of an agent harness: the runtime that
wraps a model and governs its behavior, distinct from the framework you
build an agent from.
- Rewrite the "What you can build" section to be outcome-driven — each
item maps a concrete result to the capability and doc page that delivers
it.
- Reframe "When to use the Harness" so it no longer implies the Agent
class is only for one-shot calls; the Harness is positioned as an
opinionated default for collaborative-session apps.
- Add missing reference links: model router, signals, the events
reference, and observational memory.
### Session page
- Link the first mention of `Session` to the Session reference page.
- Replace the Harness-vs-Session comparison table with a high-level
description of the Session's scope of responsibilities.
## Test plan
- Docs-only change. Verified every internal link resolves to an existing
page or in-page anchor, and confirmed the Harness Quickstart code
matches the current `Harness` API (constructor config, mode shape, and
the `init` / `selectOrCreateThread` / `sendMessage` / `subscribe`
methods) in `packages/core/src/harness`.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5 Explanation
This PR makes the Harness docs easier to understand by first explaining,
in plain terms, what the Harness is (a runtime that controls how a model
behaves) and what you can build with it. It also rewrites the Session
and Modes pages so readers know exactly what each thing tracks/controls,
and it adds missing links to related references.
## Overview Changes
**docs/src/content/en/docs/harness/overview.mdx**
- **Sharper definition up front:** Replaces earlier wording with a clear
explanation that the Harness is a **runtime** that wraps a model and
governs its behavior (separate from the agent/framework used to build an
agent).
- **Outcome-driven “What you can build”:** Rewrites the section to map
concrete results to capabilities, including:
- Persistent threads/state management
- Tool-approval gating
- Modes on a single thread
- Runtime model switching
- Subagents
- Live UI/event driving
- Long-lived autonomous agents
- **Reframed “When to use the Harness”:** Positions the Harness as an
opinionated default for **collaborative-session** apps, clarifying that
`Agent` is better suited for full control or one-shot calls.
- **Reference link gaps filled:** Adds missing links for the **model
router**, **signals**, the **events reference** (including
`HarnessDisplayState`), and **observational memory**.
## Session Page Changes
**docs/src/content/en/docs/harness/session.mdx**
- **Removed “Harness vs. Session” comparison:** Replaces it with a
clearer, high-level description of the Session’s scope.
- **Better Session framing:** Adds “What the Session tracks,” describing
Session as per-conversation live state and breaking down Session
sub-objects in conversation-building order.
- **Follow-ups clarified:** Explains that follow-ups added during an
active run are queued on `session.followUps`, and introduces mid-run
redirection via `harness.steer({ content })` (signals-based).
- **Display state rewritten and concretized:** Updates
`session.displayState` to a **reducer-maintained snapshot** that folds
harness events into a single `HarnessDisplayState` object, including
guidance to **subscribe and render** when `display_state_changed` fires.
- **First `Session` mention linked:** The initial use of `Session` on
the page now links to the Session reference.
## Modes Page Changes
**docs/src/content/en/docs/harness/modes.mdx**
- **What a mode is (and that it’s required):** Adds a clear explanation
that modes must be provided and what they consist of (e.g.,
instructions, tools, model).
- **Startup/selection behavior clarified:** Documents what happens when
modes are empty and how the default mode is chosen (via metadata like
`default` / `defaultModeId`, or the first mode).
- **Querying modes clarified:** Expands guidance that the Harness owns
the mode catalog while the Session tracks the active mode, referencing
`harness.listModes()`, `harness.session.mode.get()`, and
`harness.session.mode.resolve()`.
## Testing / Validation Notes
- Internal links were verified to resolve correctly.
- Harness Quickstart code was confirmed to match the current Harness API
in `packages/core/src/harness` (constructor config, mode shape, and
`init`, `selectOrCreateThread`, `sendMessage`, `subscribe`).
- Changes are documentation-only.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>
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
2 participants
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
Improves the Harness documentation so it explains what a harness is and what it's for before diving into APIs.
Harness overview
Session page
Sessionto the Session reference page.Test plan
HarnessAPI (constructor config, mode shape, and theinit/selectOrCreateThread/sendMessage/subscribemethods) inpackages/core/src/harness.ELI5 Explanation
This PR makes the Harness docs easier to understand by first explaining, in plain terms, what the Harness is (a runtime that controls how a model behaves) and what you can build with it. It also rewrites the Session and Modes pages so readers know exactly what each thing tracks/controls, and it adds missing links to related references.
Overview Changes
docs/src/content/en/docs/harness/overview.mdx
Agentis better suited for full control or one-shot calls.HarnessDisplayState), and observational memory.Session Page Changes
docs/src/content/en/docs/harness/session.mdx
session.followUps, and introduces mid-run redirection viaharness.steer({ content })(signals-based).session.displayStateto a reducer-maintained snapshot that folds harness events into a singleHarnessDisplayStateobject, including guidance to subscribe and render whendisplay_state_changedfires.Sessionmention linked: The initial use ofSessionon the page now links to the Session reference.Modes Page Changes
docs/src/content/en/docs/harness/modes.mdx
default/defaultModeId, or the first mode).harness.listModes(),harness.session.mode.get(), andharness.session.mode.resolve().Testing / Validation Notes
packages/core/src/harness(constructor config, mode shape, andinit,selectOrCreateThread,sendMessage,subscribe).