## Summary
`browser_screenshot` returns the image to the model, but never as a
file. When an agent wanted to share or attach a screenshot, it had no
file to point at, so agents worked around it by installing their own
browser in the sandbox just to capture a PNG.
`browser_screenshot` now takes an optional `path`. With it, the PNG is
also written to that path in the agent's workspace (missing folders are
created), and the tool result says where it was saved. If it can't be
saved (for example, the agent has no workspace), the screenshot is still
returned and the result says why.
## Test plan
- New `screenshot.test.ts` uses a real `Workspace` with a
`LocalFilesystem`: the PNG lands at the given path with folders created,
the model is told where the file went, nothing is written without
`path`, and when there's no workspace or the write fails the model still
gets the image plus the reason. Removing the feature fails the save
tests; dropping the image on a failed save fails both failure tests.
- `browser_screenshot` reference docs list the new `path` option.
- `@mastra/agent-browser` suite: 14 files, 233 tests pass.
- In a Factory session, the agent called `browser_screenshot` with a
path and attached the saved file to Slack, with no browser install in
the sandbox.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
`browser_screenshot` can now save a screenshot as a PNG in the agent’s
workspace. If it cannot save the file, it still returns the screenshot
and explains why.
## Changes
- Added an optional, non-empty `path` parameter to `browser_screenshot`.
- When `path` is set and the screenshot includes image data, the tool
resolves the workspace filesystem for the request when available. It
falls back to the static filesystem for compatibility.
- The tool creates missing folders and checks workspace write settings
before saving. It passes `{ path, overwrite: true }` to those checks.
- On success, the tool reports the saved path. If saving is unavailable
or fails, it reports the reason and still returns the image.
- Updated the reference documentation and added tests for saving,
filesystem resolution, no-path behavior, write restrictions, and error
handling.
Test execution results and review finding counts were not provided.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: CalebBarnes <CalebBarnes@users.noreply.github.com>
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
Enables `no-else-return: error` in the root Oxlint config and removes
186 redundant `else` branches across 111 source/test files. Existing
rule defaults are retained.
Reviewed every code diff for behavior preservation. An independent
TypeScript AST comparison confirms that changes are limited to removing
`else` after returning branches, with the same expressions, statement
order, return values, and `try`/`catch`/`finally` boundaries. All
181,158 identifier occurrences retain their bindings. The recorder
replay path keeps an explicit block: flattening it would shadow the
earlier request `body` with the response `body` and introduce a
temporal-dead-zone error.
Extends the existing monorepo optimized-dependency test to assert that a
raw TypeScript workspace package, including its enum and transitive
dependency, still executes in the production bundle.
Validation: the root rule-only scan passes on 15,273 files with zero
diagnostics; formatting and `git diff --check` pass. Schema
compatibility tests: 1,060 passed, 9 skipped. Recorder runtime tests: 21
passed. The core selection initially passed 3,513 tests; rerunning the
suites requiring local server/cache access passed 185 tests, with one
remaining cache-file assertion also reproduced on unchanged `main`.
Remaining validation limits: four asset-download cases cannot reach
`placehold.co`; the changed-file lint run reports six import-order
errors reproduced on unchanged files from `main`. Deployer unit tests
and the monorepo test could not run because this checkout lacks required
package dependencies (`fs-extra`/workspace links and `get-port`,
respectively). These limits are left visible for CI. No changeset is
included because this is a behavior-preserving lint cleanup.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
This PR makes the code easier to read by removing `else` branches that
are not needed after a return. It also enables a rule that catches those
branches and adds a test for loading a raw TypeScript workspace package
in a production bundle.
## Summary
- Enables Oxlint’s `no-else-return` rule at error severity and removes
186 redundant `else` branches across 111 files.
- Extends the monorepo optimized-dependencies test to check a raw
TypeScript workspace package, its enum, and a transitive dependency.
- Updates the deployer’s transpile-package path pattern.
- In workflow event processing, a truthy branch index with no matching
child now falls through to publish a skipped-step end event. Previously,
this case published no event.
- Keeps the recorder replay block explicit to avoid request/response
`body` shadowing and a temporal-dead-zone error.
## Validation
Reported checks passed: the rule-only scan across 15,273 files,
formatting, `git diff --check`, schema compatibility tests (1,060
passed, 9 skipped), recorder runtime tests (21 passed), and an initial
core test selection (3,513 passed).
Some test limits remain. Four asset-download cases could not reach
`placehold.co`. Changed-file lint reported six import-order errors that
also occur on unchanged files from `main`. Deployer unit tests and the
monorepo test could not run because dependencies were unavailable. On
rerun, suites requiring local server/cache access had 185 passes; one
cache-file assertion also reproduced on unchanged `main`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
Some tests had the same body as another test in the same file but a
different name. A few were plain copy-paste duplicates. Others were
named after behavior they never set up, so that behavior wasn't being
tested.
**Removed (exact duplicates of a test in the same file):** agent-browser
`close`, Linear `agent-tools`, factory `workspace` (private-session
refusal), playground-ui `filter-spans-keeping-ancestors`, server
`system` (cmsEnabled false), client-js `listThreadMessages` default,
workflow `request-context-schema`, OM async config, `model.test.ts`
"rate limiting"/"step change logging" tests that checked nothing, and 4
`aisdk` variants in `model.loop.e2e.test.ts` (they sent the same
requests as the `mastra` ones).
**Fixed so they test what they're named after:**
- `model.test.ts`: two tool tests that checked nothing are replaced by
one that asserts tools reach the provider as function definitions.
- language-detector / moderation / prompt-injection-detector: "default"
tests now assert the defaults appear in the prompt sent to the model,
not just `.id`.
- trailing-assistant-guard: now covers `structuredOutput` that is
present but has no schema.
- storageWithInit: the default test really leaves `disableInit` unset.
- client-js observability: the "string dates" test now actually passes
strings.
- turbopuffer: the "$and operator" test now uses explicit `$and`.
- keyboard shortcuts: the page-mount-order test now mounts the page
after the global binding.
Tests only; no runtime changes.
## Test plan
- [x] Affected suites pass in core, memory, server, client-js,
playground-ui, agent-browser, factory (Linear)
- [x] Prettier clean; turbopuffer/client-js typecheck clean for touched
files
- Note: `factory/src/workspace.test.ts` "loads every checkout's
AGENTS.md…" also fails on main; unrelated
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR removes tests that repeat other tests or do not check what their
names say they check. It also fixes several tests so they check the
intended behavior more directly.
## Summary
- Removed duplicate or ineffective tests across core, memory, server,
client-js, playground-ui, agent-browser, and Factory.
- Updated tool tests to verify provider function definitions, and
updated processor tests to inspect prompts for default language and
detection categories.
- Corrected test inputs for structured output, storage initialization,
string dates, explicit `$and` clauses, and keyboard shortcut mount
order.
- No runtime changes are reported.
## Test status
The PR reports that affected suites pass in core, memory, server,
client-js, playground-ui, agent-browser, and Factory (Linear). It also
reports clean Prettier and typechecks for the touched turbopuffer and
client-js files.
The PR notes that `factory/src/workspace.test.ts` fails on `main`
because it loads every checkout's `AGENTS.md`; the failure is reported
as unrelated.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
## Description
Fixes#18868
`AgentBrowser.click` / `press` / `select` start the `waitUntil`
navigation wait **before** awaiting the action, and no rejection handler
is attached to the navigation promise until `await navigation` is
reached:
```ts
const navigation = input.waitUntil ? page.waitForNavigation({ waitUntil: input.waitUntil, timeout }) : undefined;
await locator.click({ ... }); // ← while this is pending, `navigation` has no handler
await navigation;
```
Because the navigation wait and the action **share the same `timeout`**
and the navigation timer starts first, any action that is slow or
blocked long enough to time out lets the navigation rejection fire first
— while `await navigation` has not been reached. The rejection is
unhandled and, with Node's default behavior, **kills the entire
process** (in our case a `mastra dev` server hosting all agents went
down mid-request), even though the tool call itself returned a graceful
error object.
## Fix
Attach a noop handler right after starting the navigation wait in all
three sites (`click`, `press`, `select`):
```ts
const navigation = input.waitUntil ? page.waitForNavigation({ waitUntil: input.waitUntil, timeout }) : undefined;
navigation?.catch(() => {});
```
The rejection is always observed, and `await navigation` still surfaces
the original error through the existing try/catch, so error behavior of
the tools is unchanged.
## Testing
- Added a regression test that drives `click` with `waitUntil` while the
navigation wait rejects before the click settles, asserting no
`unhandledRejection` escapes.
- Verified the test **fails without the fix** (unhandled rejection
observed) and **passes with it**.
- Note: the test replaces the `waitForNavigation` mock with a plain
function for this case — vitest attaches handlers to promises returned
from `vi.fn()` mocks (for `mock.settledResults`), which would mask the
unhandled rejection.
- Full package suite: `browser/agent-browser` — 12 files / 221 tests
pass.
- `tsc --noEmit` and `eslint` clean for the package.
- Also reproduced the original crash outside tests with a real browser
(link covered by an overlay + `waitUntil: 'domcontentloaded'`): the tool
returned `element_blocked` gracefully while the dangling navigation
rejection escaped as an unhandled rejection.
## Changeset
Added a `patch` changeset for `@mastra/agent-browser`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
When the browser tool does a **click**, **press**, or **select**, it
also waits for the page navigation to finish. This fix ensures that if
navigation fails first, the error is still “caught” so Node won’t
crash—while the tool still returns the normal failure result.
## Summary
- Refactored `click`, `press`, and `select` to use a shared
`startNavigationWait(...)` helper that immediately attaches a noop
`navigation?.catch(() => {})` right after creating the
`waitForNavigation` promise.
- Kept the existing behavior of awaiting the navigation promise after
the DOM action, preserving the usual tool error surface.
- Added regression tests for **click**, **press**, and **select** that
simulate a “dangling navigation wait” (navigation rejects while the
action is still pending) and assert no `unhandledRejection` escapes.
- Added a Changesets entry for a patch release of
`@mastra/agent-browser`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Ehindero Israel <ehindero@Ehinderos-MacBook-Pro.local>
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.
⚠️⚠️⚠️⚠️⚠️⚠️
`main` is currently in **pre mode** so this branch has prereleases
rather than normal releases. If you want to exit prereleases, run
`changeset pre exit` on `main`.
⚠️⚠️⚠️⚠️⚠️⚠️
# Releases
## @mastra/core@1.42.0-alpha.1
### Minor Changes
- Added agent and workspace tool hooks for applications that need to run
logic before and after tool calls execute. Mastra Code now uses agent
hooks so hook handlers run for built-in workspace tools as well as
dynamic tools.
([#17637](https://github.com/mastra-ai/mastra/pull/17637))
**Example**
```ts
const agent = new Agent({
name: 'Support Agent',
instructions: 'Help users.',
model,
hooks: {
beforeToolCall: ({ toolName, input }) => {
console.log(`Running ${toolName}`, input);
},
afterToolCall: ({ toolName, output, error }) => {
console.log(`Finished ${toolName}`, { output, error });
},
},
});
const workspace = new Workspace({
tools: {
hooks: {
beforeToolCall: ({ toolName, workspaceToolName, input }) => {
console.log(`Running ${toolName} from ${workspaceToolName}`, input);
},
},
},
});
```
### Patch Changes
- Plan due notification dispatches per thread from a single due snapshot
so high-priority notifications that already emitted summaries are
delivered in full before lower-priority notifications or summaries can
wake the same thread. `Agent.sendNotificationSignal` also accepts an
array of notification inputs so related notifications can be evaluated
against the same initial thread state before any delivery wakes the
thread. ([#17590](https://github.com/mastra-ai/mastra/pull/17590))
- Fixed medium-priority notification summaries so they wake idle agent
threads when they are ready to deliver.
([#17590](https://github.com/mastra-ai/mastra/pull/17590))
- Fixed browser state signals so they no longer show 'Browser is closed'
before the browser is used. Added attribution for browser closes and
active URL changes when the agent or user caused them.
([#17631](https://github.com/mastra-ai/mastra/pull/17631))
## @mastra/agent-browser@0.3.1-alpha.0
### Patch Changes
- Fixed browser state reporting to identify when the agent or user
closed the browser or changed the active URL.
([#17631](https://github.com/mastra-ai/mastra/pull/17631))
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
## @mastra/client-js@1.24.0-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
## @mastra/react@0.5.3-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/client-js@1.24.0-alpha.1
## @mastra/deployer-cloud@1.42.0-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/deployer@1.42.0-alpha.1
## @mastra/longmemeval@1.0.49-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
## @mastra/opencode@0.0.46-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
## mastracode@0.22.3-alpha.1
### Patch Changes
- Increased TUI chat scroll buffer from 200/100 to 5000/3000 components,
so you can scroll back much further in conversation history
([#17633](https://github.com/mastra-ai/mastra/pull/17633))
- Fixed state signal placement in streamed MastraCode output.
([#17631](https://github.com/mastra-ai/mastra/pull/17631))
- Fixed the GitHub PR badge in MastraCode so it animates only while
GitHub polling is actively running, instead of restarting whenever the
agent processes a user message.
([#17590](https://github.com/mastra-ai/mastra/pull/17590))
- Added agent and workspace tool hooks for applications that need to run
logic before and after tool calls execute. Mastra Code now uses agent
hooks so hook handlers run for built-in workspace tools as well as
dynamic tools.
([#17637](https://github.com/mastra-ai/mastra/pull/17637))
**Example**
```ts
const agent = new Agent({
name: 'Support Agent',
instructions: 'Help users.',
model,
hooks: {
beforeToolCall: ({ toolName, input }) => {
console.log(`Running ${toolName}`, input);
},
afterToolCall: ({ toolName, output, error }) => {
console.log(`Finished ${toolName}`, { output, error });
},
},
});
const workspace = new Workspace({
tools: {
hooks: {
beforeToolCall: ({ toolName, workspaceToolName, input }) => {
console.log(`Running ${toolName} from ${workspaceToolName}`, input);
},
},
},
});
```
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda),
[`f2ab060`](f2ab060162)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/github-signals@0.1.1-alpha.0
- @mastra/agent-browser@0.3.1-alpha.0
## mastra@1.12.3-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/deployer@1.42.0-alpha.1
## @mastra/deployer@1.42.0-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/server@1.42.0-alpha.1
## @mastra/mcp-docs-server@1.1.46-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
## @mastra/playground-ui@33.0.0-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/client-js@1.24.0-alpha.1
- @mastra/react@0.5.3-alpha.1
## @mastra/server@1.42.0-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
## @mastra/express@1.3.30-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/server@1.42.0-alpha.1
## @mastra/fastify@1.3.30-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/server@1.42.0-alpha.1
## @mastra/hono@1.4.25-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/server@1.42.0-alpha.1
## @mastra/koa@1.5.13-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/server@1.42.0-alpha.1
## @mastra/nestjs@0.1.14-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/server@1.42.0-alpha.1
## @mastra/github-signals@0.1.1-alpha.0
### Patch Changes
- Gate GitHub signal notifications behind author permission checks to
guard against prompt injection from random commenters. Only comments
from users with write access (admin, maintain, write) trigger
notifications. Bot comments are opt-in via an allowlist that defaults to
CodeRabbit and Devin, with `ignoredBots` still available as an explicit
blocklist. Unauthorized latest comments are excluded before notification
classification so noisy bot edits do not render in notification metadata
or mask the latest authorized comment. Scheduled polls now include
comments and detect latest-comment timestamp changes so comment
notifications are not lost behind stale or unchanged thread hashes.
Comment activity notifications render the latest authorized comment
author and excerpt as high-priority GitHub signal updates.
([#17590](https://github.com/mastra-ai/mastra/pull/17590))
New options on `GithubSignalsOptions`:
- `authorizedPermissions` — permission levels that authorize human
commenters (default: `['admin', 'maintain', 'write']`)
- `authorizedBots` — bot logins authorized to trigger notifications
(default: `['coderabbitai[bot]', 'devin-ai-integration[bot]']`)
- `ignoredBots` — bot logins whose comments should NOT trigger
notifications, even if authorized
- `permissionResolver` — injectable resolver for looking up collaborator
permissions (default: `gh api`)
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
## @mastra/temporal@0.1.13-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/deployer@1.42.0-alpha.1
## create-mastra@1.12.3-alpha.1
## @internal/playground@1.12.3-alpha.1
### Patch Changes
- Updated dependencies
[[`2bccba4`](2bccba4c03),
[`2bccba4`](2bccba4c03),
[`f2ab060`](f2ab060162),
[`5d302c8`](5d302c8eda)]:
- @mastra/core@1.42.0-alpha.1
- @mastra/client-js@1.24.0-alpha.1
- @mastra/react@0.5.3-alpha.1
- @mastra/playground-ui@33.0.0-alpha.1
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Description
Two fixes to the browser state signal:
1. **Suppress "Browser is closed" when the agent never used the
browser** — if there's no previous state signal (browser was never
reported as open) and the browser is currently closed, the signal is
suppressed entirely. This prevents confusing messages when an agent has
a browser configured but the user/agent hasn't actually used it.
2. **Add `closeReason` to differentiate why the browser closed** — new
optional field on `BrowserContext` with values `'agent' | 'user' |
'process_restart' | 'error'`. The formatted state signal message changes
based on the reason:
- `process_restart` → "The session process restarted, which closed the
browser."
- `user` → "The user closed the browser."
- `error` → "Browser closed unexpectedly due to an error."
- `agent`/default → "Browser is closed."
The `closeReason: 'error'` is now set in `agent.ts` when
`getBrowserState()` throws. Other reasons (`process_restart`, `user`)
can be set by callers that have that context (e.g. the session runtime
or viewer registry).
## Related issue(s)
Fixes the issue discussed in Slack where the state signal showed
"Browser is closed" even when the agent hadn't used the browser at all.
## Type of change
- [x] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
## Checklist
- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR
Link to Devin session:
https://app.devin.ai/sessions/34fece46417c4d0cb01a1a73e3871126
Requested by: @TylerBarnes
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
The PR prevents a misleading "Browser is closed" message when the agent
never opened the browser and attaches a short reason for why a browser
closed (agent, user, process restart, or error) so state messages are
accurate and useful.
## Changes Summary
### Core Changes
- Suppress spurious closed signals
- computeStateSignal() no longer emits a plain "Browser is closed" state
when the thread has never previously reported the browser open; closed
signals are only emitted when there is a meaningful prior open-state in
the thread history.
- Adds logic to avoid emitting ambiguous "bare closed" deltas.
- Close reason tracking and messaging
- BrowserContext / persisted BrowserState gains optional closeReason?:
'agent' | 'user' | 'process_restart' | 'error'.
- computeStateSignal preserves or infers closeReason and uses it to
format messages:
- process_restart → "The session process restarted, which closed the
browser."
- user → "The user closed the browser."
- error → "Browser closed unexpectedly due to an error."
- agent/default → "Browser is closed."
- Delta formatting for open: false uses the closeReason text instead of
a generic closed message.
- Agent error-handling
- packages/core/src/agent/agent.ts: when getBrowserState() throws, the
resolver returns { isOpen: false, closeReason: 'error' } so exceptions
are attributed to 'error'.
### Browser / Agent-Browser Changes
- AgentBrowser
- Tracks per-thread (and default) close reasons and agent-driven
active-URL changes.
- Persists thread-aware closed state including tracked closeReason and
activeUrlChangeSource.
- Clears tracking maps on launch; closeThreadSession override saves
thread-specific last state.
- getBrowserState(threadId) routes through thread-aware logic to include
closeReason/activeUrlChangeSource.
- Close tool
- createCloseTool records agent-initiated closeReason ('agent')
(thread-aware) before closing.
- Navigation tools
- goto/back/new/switch record agent-driven URL changes so
activeUrlChangeSource can be attributed correctly.
### Persistence & Thread Manager
- Thread-manager persistence schema updated to include optional
closeReason and activeUrlChangeSource.
- updateBrowserState now shallow-copies incoming state and preserves
extra fields (so closeReason/activeUrlChangeSource are not dropped).
### Mastracode / UI Streaming Fix
- Anchors streamed state_signal components before the active assistant
text component so later assistant text updates do not push the signal
down the chat stream.
- Adds a TUI regression test ensuring the state signal is inserted and
the streamed assistant text renders correctly.
### Tests & Docs
- Extensive tests added/updated:
- computeStateSignal tests expanded to cover suppression when browser
was never opened, open-from-remembered-closed with active URL
propagation, close reason attribution (process_restart, user, error),
activeUrlChangeSource attribution (agent vs user), and suppression when
only source metadata toggles.
- agent-browser tests verify preservation and correct inheritance of
closeReason and activeUrlChangeSource behavior.
- mastracode TUI tests added to verify anchored state signal behavior.
- Changesets updated to document patch releases for `@mastra/core`,
`@mastra/agent-browser`, and `mastracode`.
- Minor CI/test/ESLint adjustments included.
### API / Interface Changes
- Interface updates:
- BrowserContext / BrowserState: added closeReason?: 'agent' | 'user' |
'process_restart' | 'error'
- BrowserState: added activeUrlChangeSource?: 'agent' | 'user'
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: tyler <tylerdbarnes@gmail.com>
Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>