0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/docs
Ward Peeters da04116579
feat(factory): let a person's reply wake a card's session while automated runs hold every slot (#30307)
## What

When a trusted collaborator comments on or reviews a card's GitHub pull
request or issue, Factory wakes the card's session even while automated
runs hold every run slot. Before, those replies were
`sendMessage`/`signalActivity` decisions that counted against the single
automated cap (`dispatcher.maxInFlight`, default 10), so a reply could
sit behind multi-hour triage runs.

## How

- **Provenance.** GitHub rule actors gain `human: true` when the webhook
`sender.type` is `User`. Bots, and Factory's synthetic reconciler events
(no `sender.type`), get `human: false`.
- **Classification** (`isInteractiveDecision`, `rules/dispatcher.ts`): a
decision is a reply only if it's `sendMessage` or `signalActivity`,
would wake the session (`idleBehavior` isn't `persist`), has an empty
causal chain (no rule passed it along, e.g. not a transition's message),
and its actor is a GitHub human who is trusted and not Factory.
Everything else stays automated. GitLab, Linear, Jira and incident.io
activity stays automated because those sources give no reliable
bot/human signal.
- **Lane.** Each process keeps a reserve of reply slots
(`dispatcher.maxInteractiveInFlight` /
`MASTRACODE_DISPATCH_MAX_INTERACTIVE_IN_FLIGHT`, default `2`, `0`
allowed). Claim order per tick: pending manual starts → replies (reserve
first, then borrowing free automated slots) → automated runs. The claim
filter now receives the row's `actor` and `causalChain` as well as the
decision payload, so no schema change.
- **Honest bounds.** The caps limit dispatcher slot occupancy, not total
running agents: `signalActivity` frees its slot once the session accepts
it, and UI/Slack messages plus approval notices to following sessions go
to the session directly and never wait for a slot. The README says so.
- **Run-queue API (additive).** Entries gain `lane`; the response gains
`queuedByLane`, and `slots` gains `interactive: { inUse, cap }`.
Existing fields keep their meaning. `position` now counts within a lane.
The board's queue menu lists waiting replies first, with a reply-slot
footer.

## Testing

- Dispatcher (LibSQL + throwaway Postgres): with automated cap 1 held by
a hanging run, a trusted person's PR reply (`sendMessage`) and issue
comment (`signalActivity`) are claimed and delivered. Automated runs,
bot replies, untrusted replies, Factory-authored replies, actors with no
`human` flag, rule-passed messages and `persist` activity all stay
pending. Other cases: the reserve caps at its size, replies borrow a
free automated slot ahead of automated runs, and the default reserve is
2. Red proof: disabling the classification fails 3 of the 4 lane tests.
- GitHub rules: `issue_comment` and `pull_request_review` from a User →
`human: true`; from a Bot or without `sender.type` → `human: false`.
- Approval notice to a following session commits nothing to the run
queue.
- MSW: queue menu groups replies apart from automated runs and shows
both slot footers.
- Gates: factory `check`, oxlint and oxfmt clean. Factory suites on
LibSQL: 942 passed. factory-ui typecheck and lint clean; unit tests 696
passed. The full MSW suite has 21 failures, the same as on main
(AppStartup, OMSection, MemorySettings, NewSessionStarters,
ThreadPageTeammateSession, TranscriptMessageMeta). `mastracode/web`
index.test.ts has 2 failures that are also on main. Postgres runs of the
full dispatcher suite at `--maxWorkers=3` show the timing flakes main
already has; every test that failed passes on its own.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

**ELI5:** When a trusted person replies to a GitHub issue or pull
request, that reply gets its own reserved run slots. It no longer waits
behind routine automated runs.

## Overview

This change adds an interactive lane to the Factory decision dispatcher.
Trusted GitHub human replies can wake a card's session while automated
runs hold the automated slots. The run-queue API changes are additive.

## Classification

`isInteractiveDecision` in `mastracode/factory/src/rules/dispatcher.ts`
marks a decision as interactive only when all of these hold:

- The decision is `sendMessage` or `signalActivity`.
- The decision wakes the session.
- The causal chain is empty.
- The decision does not persist.
- The actor is a trusted GitHub human.
- The actor is not Factory-authored.

All other decisions use the automated lane. This includes bot actors,
untrusted actors, Factory events, and activity from GitLab, Linear,
Jira, and incident.io.

## GitHub actor changes

- `mastracode/factory/src/rules/types.ts` adds optional `human?:
boolean` to the GitHub variant of `FactoryRuleActor`.
- `mastracode/factory/src/integrations/github/rules.ts` sets `human` to
`true` only when the webhook sender type is exactly `User`.
- Trust lookup and its failure handling are unchanged. A lookup error
still marks the actor untrusted.

## Dispatcher behavior

- The default interactive reserve is 2 slots per process.
- `dispatcher.maxInteractiveInFlight` in
`mastracode/factory/src/factory.ts` and
`MASTRACODE_DISPATCH_MAX_INTERACTIVE_IN_FLIGHT` in
`mastracode/web/src/mastra/index.ts` set the reserve.
- A value of `0` disables the reserve. Invalid values use the default of
2.
- Each tick claims in this order: pending manual starts, then
interactive decisions, then automated deferred runs.
- Interactive decisions can use free automated slots.
- `runSlots()` returns overall `inUse` and `cap`, plus `interactive: {
inUse, cap }`.
- The caps limit dispatcher-held slots. They do not limit all running
agents.
- Pull-request activity releases its slot when the session accepts it.
- Direct session messages and approval notices do not wait for a slot.

## Storage

- `FactoryDeferredDecisionClaimInput.decisionFilter` receives a second
argument, `provenance`.
- The new `FactoryDecisionProvenance` type contains `actor` and
`causalChain`.
- No schema change is made. Invalid stored actor JSON parses to `null`.
Invalid causal-chain JSON parses to an empty array.

## Run-queue API (additive)

- `runQueueResponseSchema` in
`mastracode/factory/src/routes/contracts.ts` adds:
  - `slots.interactive: { inUse, cap }`
  - `queuedByLane: { automated, interactive }`
- Each queue entry has a `lane` field with the value `automated` or
`interactive`.
- `position` counts within a lane.
- The listing limit of 50 entries is unchanged. Waiting replies are
listed before automated runs.
- The `runSlots` types in `routes/surface.ts` and `routes/work-items.ts`
include the interactive pool.

## Board UI

- `RunQueueIndicator.tsx` lists waiting replies before automated runs.
- Each nonempty group has a label.
- The menu shows reply-slot usage next to overall slot usage.
- The tooltip fallback reads "Runs waiting for a run slot."
- `msw-server.ts` and `BoardPageRunQueue.msw.test.tsx` add lane fixtures
and a test for a waiting reply.

## Documentation and release notes

- `mastracode/factory/README.md`,
`docs/src/mastra-code/configuration.mdx`, and two changesets describe
the reserve, its default, the `0` behavior, the queue fields, and the
board ordering.
- The `mastra` changeset is a patch. The `@mastra/factory` changeset is
a minor release.

## Tests

Added or updated tests cover:

- GitHub actor `human` classification for issue comments and PR reviews,
for `User`, `Bot`, and missing sender types.
- Dispatcher reserve use, interactive cap overflow, borrowing of free
automated slots, and exclusions. Exclusions include automated, bot,
untrusted, Factory-authored, untyped, causally moved, and persisted
messages.
- The default interactive cap of 2.
- The polling-loop claim count, which changes from two to three per
tick.
- Factory config forwarding in
`mastracode/web/src/mastra/index.test.ts`, which now expects
`maxInteractiveInFlight: 0` when the environment variable is `0`.
- Clearing `MASTRACODE_DISPATCH_MAX_INTERACTIVE_IN_FLIGHT` in
sandbox-provider tests.
- No deferred decisions recorded after approval-notification delivery,
in `approval-answer-resume.test.ts`.

## Validation (author-reported)

The PR objectives report the following results. They were not checked
against completed CI checks on the current head.

- Dispatcher tests were run on LibSQL and throwaway Postgres. Full
Postgres dispatcher runs at `--maxWorkers=3` showed timing flakes. The
author reports that each failing test passes when run alone.
- Factory suites on LibSQL report 942 passing tests.
- Factory `check`, oxlint, and oxfmt are reported clean.
- factory-ui unit tests report 696 passing tests.
- The author reports 21 full MSW suite failures and 2 `mastracode/web`
`index.test.ts` failures. The author states these also occur on `main`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
History 2026-11-16 16:12:18 +01:00
..
scripts fix(docs): fail pnpm check when Vale is missing (#30334) 2026-11-13 10:42:46 -07:00
src feat(factory): let a person's reply wake a card's session while automated runs hold every slot (#30307) 2026-11-16 16:12:18 +01:00
static feat(ui): rounded squircle favicon for Studio, Factory and docs (#30040) 2026-11-11 14:20:52 +04:00
styleguides feat(docs): one pnpm check command for all docs checks, with JSON output and stable rule IDs (#29801) 2026-11-09 16:59:20 -07:00
styles docs: improve agent-facing llms.txt and clear Vale AI-tell findings (#25437) 2026-09-29 07:44:10 -07:00
tests docs: reframe sandboxes and filesystems guidance (#21786) 2026-08-20 11:17:58 +01:00
.env.example Kenny/grwth 1163 move chatbotsidebar button to middle (#10586) 2025-11-27 14:13:02 +01:00
.gitignore Tests: e2e tests for docs (#13483) 2026-02-26 12:21:00 +01:00
.oxfmtrc.json chore(docs): Remove remnants of JP i18n (#20635) 2026-08-03 15:58:27 +02:00
.remarkrc.mjs chore(docs): Use oxfmt (#20305) 2026-07-28 16:35:37 +02:00
.vale.ini docs: @mastra/connect — platform integrations guide, quickstart, API + provider reference (#25863) 2026-10-07 10:04:43 -04:00
AGENTS.md feat(docs): one pnpm check command for all docs checks, with JSON output and stable rule IDs (#29801) 2026-11-09 16:59:20 -07:00
CHANGELOG.md chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
CLAUDE.md chore(repo): Cleanup files (#15434) 2026-04-16 11:30:13 +02:00
CONTRIBUTING.md feat(docs): one pnpm check command for all docs checks, with JSON output and stable rule IDs (#29801) 2026-11-09 16:59:20 -07:00
custom.css fix(docs): tighten sidebar group heading spacing (#25094) 2026-09-25 11:24:41 +01:00
docusaurus.config.ts docs: Knowledge for agents (#28939) 2026-11-03 16:05:54 -08:00
lint-staged.config.mjs docs: retire guides section (#21329) 2026-08-12 15:17:06 +02:00
package.json chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
playwright.config.ts Tests: e2e tests for docs (#13483) 2026-02-26 12:21:00 +01:00
README.md feat(docs): register a WebMCP search_documentation tool on docs pages (#29922) 2026-11-10 11:31:00 -07:00
tsconfig.json feat(docs): Add llms.txt to every route (#12466) 2026-01-29 10:26:02 -08:00
turbo.json fix(docs): fail production builds when search or Ask AI credentials are missing (#28577) 2026-10-27 14:23:55 +01:00
vercel.json docs: redirect commonly hallucinated docs URLs to real pages (#30126) 2026-11-11 16:07:08 -07:00
vercel.redirects.json docs: redirect commonly hallucinated docs URLs to real pages (#30126) 2026-11-11 16:07:08 -07:00
vitest.config.ts chore(docs): Move storage/project structure (#19049) 2026-07-08 11:54:37 +02:00

Mastra Documentation

Welcome to the home of Mastra's documentation! Everything you see on mastra.ai/docs is sourced from this directory.

Want to contribute? Check out our contribution guidelines for details on how to get started.

Here's a quick start to run the docs locally

  • Install dependencies:

    pnpm install
    
  • Start the development server:

    pnpm run dev
    

Linting

Run every docs check (formatting, frontmatter, sidebars, structure, links, remark, Vale, and redirects) with one command:

pnpm run check

Add --fix to apply safe fixes or --format json for machine-readable output. See styleguides/CHECKS.md for every rule ID. The individual linters below still work on their own.

Remark

To lint Markdown files according to remark rules (e.g. enforcing consistent heading levels, list markers, etc.), you can use remark:

pnpm run lint:remark

Vale

Vale is a syntax-aware linter for prose that can help enforce style and grammar rules. We use it to maintain consistency across our documentation.

  1. Run the Vale download script to fetch a binary:

    pnpm run vale:download
    
  2. Then you can run the Vale linter:

    pnpm run lint:vale
    

Agent features

WebMCP

WebMCP is an experimental browser API that lets a page offer tools to an agent running in the reader's browser. Every docs page registers one tool, search_documentation, from src/theme/webmcp/ (mounted in src/theme/Root.tsx).

  • Input: query (string, required, at most 500 characters) and limit (integer, 1 to 20, default 5).
  • Result: { results: [{ title, heading, url, markdownUrl, excerpt }] }, where url is absolute and anchored, markdownUrl is the page's .md version (left out for /learn pages, which have none), and excerpt is plain text of at most 1,000 characters. Records for a page title or heading have no text in the index, so their excerpt is the heading path, such as Docs > Memory > Working memory. The tool description tells agents to fetch markdownUrl for the full page. Failures come back as { error: { code, message } } with the code invalid_input or search_failed.
  • It searches the same Algolia index as the search bar, using the @mastra/docusaurus-plugin-algolia credentials. Without those credentials (for example, local builds without ALGOLIA_* env vars) the tool isn't registered.
  • Browsers without document.modelContext (or the older navigator.modelContext) skip it entirely. The tool code loads on mount when the API and the Algolia credentials exist; the search code and the Algolia client load on the first call.

To try it, build with the ALGOLIA_APP_ID and ALGOLIA_SEARCH_API_KEY env vars set, run pnpm serve, and open a page in a browser with WebMCP enabled. In tests, inject a document.modelContext stub before the page loads (for example with Playwright's page.addInitScript) and call the registered tool's execute.