0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/mastracode
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
..
factory 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
factory-ui 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
mastra-factory chore: version packages (alpha) (#30430) 2026-11-16 14:09:31 +01:00
sdk chore(deps): use the latest @ai-sdk/provider-utils and @ai-sdk/provider patch in each major (#30518) 2026-11-16 15:17:56 +01:00
tui chore: version packages (alpha) (#30430) 2026-11-16 14:09:31 +01:00
web 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
.gitignore test: add 70 Mastra Code e2e scenarios + in-process runner (#18102) 2026-06-18 01:46:00 +02:00
AGENTS.md docs(factory): document focused test commands for mastracode/factory (#29866) 2026-11-10 04:50:02 +00:00
README.md chore(mastracode): make one command bring the whole dev stack up (#21159) 2026-08-11 07:41:11 -07:00

MastraCode contributor guide

Use this guide to find the right package and run Factory locally.

Packages

Package Responsibility
factory Factory backend: storage, routes, rules, and integrations
factory-ui Factory React application and browser tests
web Local and deployable Factory host
sdk Shared coding-agent runtime
tui Terminal interface
mastra-factory create-factory scaffolder

Setup

From the repository root:

pnpm install
pnpm --dir mastracode/web install
pnpm --dir mastracode/web run prebuild

The web host is a separate pnpm project. prebuild builds the local packages it links to.

Run Factory

First complete the local GitHub App setup.

For backend work, run the API and bundled UI together:

pnpm --dir mastracode/web dev

Open http://localhost:5873.

For UI work with hot module replacement, run the Docker services, the API, and the Vite dev server together:

pnpm --dir mastracode/web dev:ui

Open http://localhost:5173. To run them in separate terminals instead, start the Docker services with pnpm --dir mastracode/web db:up, then run pnpm --dir mastracode/web api and pnpm --filter ./mastracode/factory-ui dev.