0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/mastracode/web
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
..
e2e/web fix(agent-controller): restore stored tool suspensions (#30132) 2026-11-11 18:05:50 -08:00
scripts feat(factory): let Slack runs attach workspace files to the thread (#27351) 2026-10-21 10:39:13 -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
.env.schema feat(factory): give sessions the Platform project's Mastra Connect tools and a host tools option (#28756) 2026-11-06 22:48:44 +01:00
.gitignore feat(deployer): detect and package Software Factory deployments (#19948) 2026-07-22 22:01:26 +02:00
docker-compose.yml fix(redis-streams,valkey-streams): expire idle streams by default and clear them on thread delete (#28968) 2026-10-30 11:51:23 +01:00
package.json chore(deps): update build tools (major) (#29026) 2026-11-03 20:18:21 +01:00
pnpm-lock.yaml chore(deps): update security updates [security] (#30258) 2026-11-13 06:57:14 -08:00
pnpm-workspace.yaml chore(deps): update security updates [security] (#30258) 2026-11-13 06:57:14 -08:00
README.md feat(factory): give sessions the Platform project's Mastra Connect tools and a host tools option (#28756) 2026-11-06 22:48:44 +01:00
tsconfig.json refactor(mastracode): extract Factory UI package (#20246) 2026-07-28 02:57:13 +02:00
vitest.config.ts refactor(mastracode): extract Factory UI package (#20246) 2026-07-28 02:57:13 +02:00

MastraCode web host

mastracode/web wires environment-specific storage, authentication, integrations, event bus, and sandboxes into @mastra/factory. React code belongs in factory-ui.

This is a separate pnpm project with its own lockfile and link: dependencies to monorepo packages.

Setup

From the repository root:

pnpm install
pnpm --dir mastracode/web install
pnpm factory:build

factory:build runs this package's prebuild, which builds the linked monorepo packages required by the host. pnpm factory:dev doesn't build them, so run pnpm factory:build again after pulling changes to those packages.

Development

Guided setup

From the repository root, run the guided setup for Factory development:

pnpm factory:dev

On the first run, the setup prompts you to:

  1. Sign in to Mastra and select an organization, project, and environment.
  2. Select local LibSQL, local PostgreSQL, or a platform-managed PostgreSQL database.
  3. Select a local or platform sandbox.

Selecting local PostgreSQL starts the Docker services. Docker isn't required for LibSQL or a platform-managed database.

The setup stores non-secret selections in .factory/settings.json. It writes resolved runtime values, including an organization-scoped platform key, to mastracode/web/.env. Both files are ignored by Git. Later runs reuse this configuration and start the API on port 4111 and the Vite UI on port 5173.

To select different resources, delete .factory/settings.json and run pnpm factory:dev again. The setup replaces the environment values it manages and preserves unrelated values in mastracode/web/.env.

The linked monorepo packages must already be built. Run the commands under Setup first after a fresh checkout.

Configure local onboarding manually

Create a GitHub App with URLs matching the mode you will run:

Setting Integrated mode Split UI mode
Homepage URL http://localhost:5873 http://localhost:5173
Callback URL http://localhost:5873/auth/github/callback http://localhost:5173/auth/github/callback
Setup URL http://localhost:5873/auth/github/callback http://localhost:5173/auth/github/callback

Do not mix modes. Nothing runs on port 5173 in integrated mode.

Configure the app:

  1. Grant Contents, Issues, and Pull requests read/write access and Metadata read-only access.
  2. Clear Webhook → Active for local development.
  3. Generate a client secret and private key.
  4. Add these values to mastracode/web/.env:
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=
GITHUB_APP_SLUG=
GITHUB_APP_WEBHOOK_SECRET=

Generate the state-signing secret with openssl rand -hex 32 and use it for GITHUB_APP_WEBHOOK_SECRET. Use escaped \n characters in the private key. Restart the server after changing .env.

See .env.schema for other environment variables.

Integrated mode

Use this for backend work and production-like checks:

pnpm --dir mastracode/web dev

Open http://localhost:5873.

Split UI mode

Use this for UI work. One command starts the Docker services, builds the workspace packages the UI depends on, then runs the API on :4111 and Vite on :5173:

pnpm --dir mastracode/web dev:ui

Open http://localhost:5173. To restart one side without losing the other, 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 in separate terminals.

Slack channels (optional)

Slack sends events to public HTTPS origins only, so a local server needs a tunnel. The steps below assume integrated mode, where the server listens on 5873. Install cloudflared (brew install cloudflared).

1. Start a tunnel

cloudflared tunnel --url http://127.0.0.1:5873

Any HTTPS tunnel can be used. The command above starts a temporary Cloudflare Quick Tunnel without an account or config file. Keep it running and copy the trycloudflare.com hostname it prints; that hostname is valid until you stop the command.

If you have a Cloudflare account and a domain, use a named tunnel with a stable hostname instead. Then the Slack manifest can keep the same public URL across local restarts instead of being updated for every new Quick Tunnel hostname.

2. Create the Slack app

Generate a manifest for the tunnel URL:

pnpm --dir mastracode/web slack:manifest \
  --url https://your-tunnel-hostname \
  --name "Mastra Factory (dev)" \
  --copy

At api.slack.com/apps, choose Create New App → From a manifest and paste the manifest from your clipboard.

Install it to your workspace. Copy the app credentials from Basic Information → App Credentials and the bot token from OAuth & Permissions into .env:

MASTRACODE_CHANNELS_PUBLIC_URL=https://your-tunnel-hostname
SLACK_APP_SIGNING_SECRET=
SLACK_APP_CLIENT_ID=
SLACK_APP_CLIENT_SECRET=
SLACK_APP_BOT_TOKEN=

Restart the dev server — varlock reads .env at startup.

DM the bot. It replies with a Connect card; that flow binds your Slack identity to your Mastra user, and messages then run as you.

A quick tunnel gets a new hostname each run. When it changes, replace the hostname in MASTRACODE_CHANNELS_PUBLIC_URL and in the Slack app's Event Subscriptions, Interactivity & Shortcuts, and OAuth & Permissions settings.

Optional local services

To test PostgreSQL and Redis:

pnpm --dir mastracode/web db:up

Add these values to mastracode/web/.env and restart the server:

DATABASE_URL=postgres://user:pass@localhost:54329/mastracode_web
REDIS_URL=redis://localhost:63799

Amazon Bedrock

Bedrock authenticates with the server's AWS credentials, not a key each account saves. With sign-in enabled, turn it on for every account by adding these values to mastracode/web/.env:

FACTORY_DEPLOYMENT_MODEL_PROVIDERS=amazon-bedrock
AWS_REGION=us-east-1
# A Bedrock API key, or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, AWS_PROFILE, an ECS task role, or EKS IRSA
AWS_BEARER_TOKEN_BEDROCK=...

On EC2, an instance profile alone isn't detected. Add a profile to ~/.aws/config with credential_source = Ec2InstanceMetadata and set AWS_PROFILE to that profile.

Every signed-in account can then run Bedrock models, billed to that AWS account. Settings show Bedrock as From deployment and offer no key field. Without FACTORY_DEPLOYMENT_MODEL_PROVIDERS, Bedrock stays hidden and runs fail with a message that tells the operator what to set. Local mode without sign-in uses any AWS credentials in the environment, as before.

Google Vertex AI

Vertex AI authenticates with the server's Google Cloud Application Default Credentials (ADC). With sign-in enabled, add these values to mastracode/web/.env:

FACTORY_DEPLOYMENT_MODEL_PROVIDERS=google-vertex
GOOGLE_VERTEX_PROJECT=my-google-cloud-project
GOOGLE_VERTEX_LOCATION=us-central1

For local development, create ADC credentials with:

gcloud auth application-default login

Deployments can instead use a service account or a Google Cloud runtime identity. Every signed-in account can then run Vertex AI models using the configured project and location. Settings show Vertex AI as From deployment and offer no key field.

Mastra Connect tools

Sessions in web chat, Slack and on work items get the Mastra Connect tools of every connection attached to your Platform project, MCP servers included, for example to answer questions about Linear in a Slack thread. Attach connections in Mastra Platform, on the project's Connect page. Settings → Tools shows which ones sessions get. Platform deploys already have the credentials. Locally, set MASTRA_PROJECT_ID and MASTRA_PLATFORM_SECRET_KEY in mastracode/web/.env. Every user and organization on the server shares the project's connections. See @mastra/factory's README for which tools are left out.

Tests

pnpm --dir mastracode/web test
pnpm --dir mastracode/web check

UI tests live in factory-ui; backend tests live in factory.

Build and run

pnpm --dir mastracode/web build
pnpm --dir mastracode/web start

Deploy

mastra auth login
pnpm --dir mastracode/web deploy