From ca2f493e87a531092473548f17c3607a056cae1f Mon Sep 17 00:00:00 2001 From: "mastra-platform[bot]" <284800079+mastra-platform[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 14:23:27 -0700 Subject: [PATCH 001/239] fix(factory): give sandbox GitHub tokens access to every Factory repo, in groups of 10 (#30121) > Opened by @DSchau ## Problem The Factory mints each sandbox token for at most 10 repositories. When a Factory had more than 10 repos, the sandbox `GH_TOKEN` fell back to covering the session repository only. Raw `git`/`gh` then returned 404 for every other checkout. Secondary checkouts also had no git credential helper, so a raw `git push` never worked there, even under the limit. ## Change - The sandbox gets one token per group of 10 environment repositories. `GH_TOKEN` covers the group that holds the session repo; the other groups get `GH_TOKEN_2`, `GH_TOKEN_3`, and so on. These names were already reserved in `contracts.ts`. - Every group token is installed before setup commands run, so a setup command in any checkout can fetch. - Each secondary checkout gets a local credential helper that selects its group's token: `GH_TOKEN="${GH_TOKEN_N:-$GH_TOKEN}" gh auth git-credential`. Checkouts in group 1 keep the plain `gh auth git-credential`. Non-GitHub hosts are unchanged. - `github_refresh_token` and stale-token refresh re-mint every group. Group tokens and the coverage note are stored per workspace, so a refresh from any request installs the tokens it just minted. When an org PAT is installed, the group variables and the note are dropped and the helpers fall back to the PAT. - The environment note lists which variable covers which repos (for example `GH_TOKEN=$GH_TOKEN_2 gh pr list -R owner/repo`), along with any repos no token covers. If one group fails to mint, the session still boots; only a failure in the session repo's group is fatal. - `groupRepositoryIds` is exported from `environment/repository-access.ts` so the clone-time grouping and the sandbox grouping share one helper. Found on a 12-repo Factory (shipyard), where the docs repos returned 404 from inside the sandbox. ## Test plan - [x] Workspace test with 12 repos: two group mints, `GH_TOKEN` and `GH_TOKEN_2` in the env (stale `GH_TOKEN_N` cleared), the correct `tokenEnvName` for each checkout, the note text, and refresh re-minting both groups - [x] Workspace test with 11 repos: `GH_TOKEN_2` is installed before setup commands run, the note survives setup, a refresh from a later resolution installs fresh group tokens, and an org PAT drops the group tokens and the note (fails on the first commit) - [x] Sandbox tests: grouped helper, plain helper, no helper for non-GitHub hosts, and rejection of unsafe variable names - [x] `vitest` on factory environment/session/github/workspace suites: 1416 passed - [x] `tsc --noEmit` and `oxlint` are clean - [x] Tested the helper with real `git credential fill`: it returns `GH_TOKEN_2` when that variable is set and `GH_TOKEN` when it is not **ELI5:** Sandboxes can now reach more than 10 GitHub repositories. The sandbox gets one access token for each group of up to 10 repositories. Git in each checkout uses the token for its own repository. ## Overview This change extends GitHub token coverage for Factory sandboxes. Before this change, only the session repository had a token (`GH_TOKEN`). Repositories are now grouped in sets of up to 10. Each group has its own installation token. Diff size: 6 files changed, 339 lines added, 58 lines removed. The `mastracode/factory` paths account for 5 files, 334 insertions, and 58 deletions. The changeset file (`.changeset/sandbox-github-token-groups.md`, 5 insertions) is outside that path. ## Token groups - `groupRepositoryIds` is exported from `mastracode/factory/src/environment/repository-access.ts`. It removes duplicate repository IDs, keeps their order, and splits them into groups of at most 10. - `groupedRepositoryAccess` uses this helper. Its grouping behavior does not change. - `mastracode/factory/src/workspace.ts` mints one token per group. The session repository's group uses `GH_TOKEN`. Later groups use `GH_TOKEN_2`, `GH_TOKEN_3`, and so on. - For a multi-repository group, minting first calls `getRepositoriesAccess`. If that call fails or returns no token, the code falls back to a token for the group's first repository. ## Failure handling - Failure to mint the session repository's group token fails resolution. - Failure in a secondary group does not fail resolution. Repositories that no token covers are reported in the environment note and in warnings. ## Credential helpers - `mastracode/factory/src/integrations/github/sandbox.ts` adds `githubCredentialHelper(tokenEnvName?: string)`. - For `GH_TOKEN` (the default), the helper returns the existing `gh auth git-credential` helper. - For a name that matches `GH_TOKEN_`, the helper prefers that variable and falls back to `GH_TOKEN`. - Any other name is rejected. - `SyncEnvironmentRepositoryOptions` accepts an optional `tokenEnvName`. - `syncEnvironmentRepository` sets `credential.helper` for GitHub checkouts only when `authUsername` is unset. Non-GitHub hosts receive no credential helper. If the `git config` call fails, the sync reports `pull-failed`. - Group 1 keeps the standard helper. ## Token refresh and PAT installation - Refresh re-mints the token for every group. This includes `github_refresh_token` and stale-token refresh. - When an organization PAT is installed, the code removes the `GH_TOKEN_` variables. Helpers then fall back to the PAT. - Group-token state is cleared when a workspace is evicted or retired. ## Environment notes and warnings - When group tokens are installed, the environment note states which token covers each repository. - The note lists repositories that no token covers. It directs users to the `source_control_*` tools for those repositories. - The fallback warning reports only the uncovered repositories, not the full repository list. - When an organization PAT replaces the group tokens, the group-token note is removed. ## Other changes - The raw change summary states that lifecycle-command failure details are now passed to `maskSandboxEnvValues`, and that per-call `env` values override duplicate mask entries. This was not verified against the implementation. - The changeset describes a patch release for `@mastra/factory`. It was not verified against the changeset file. ## Tests and checks The author reports these results. This review did not run them. - A new 12-repository workspace test expects token requests in groups of 10 and 2. It checks installation as `GH_TOKEN` and `GH_TOKEN_2`, checkout-to-token mapping, the coverage note, and refresh of both groups. - A new 11-repository workspace test checks that group tokens are installed before setup. It checks that they stay current after workspace reuse. It checks that an organization PAT replaces them and clears the note. - New sandbox tests cover credential-helper selection for the default helper, numbered helpers, and non-GitHub hosts. A test covers rejection of unsafe token variable names. - The author reports 1,415 passing tests across the factory environment, session, GitHub, and workspace suites. - The author reports clean `tsc --noEmit` and `oxlint` runs. - The author reports a manual `git credential fill` check. - CI status on the current head: not available. --------- Co-authored-by: mastra-platform[bot] Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/sandbox-github-token-groups.md | 5 + .../src/environment/repository-access.ts | 12 +- .../src/integrations/github/sandbox.test.ts | 29 +++ .../src/integrations/github/sandbox.ts | 34 +++- mastracode/factory/src/workspace.test.ts | 139 ++++++++++++- mastracode/factory/src/workspace.ts | 182 +++++++++++++----- 6 files changed, 341 insertions(+), 60 deletions(-) create mode 100644 .changeset/sandbox-github-token-groups.md diff --git a/.changeset/sandbox-github-token-groups.md b/.changeset/sandbox-github-token-groups.md new file mode 100644 index 00000000000..1bdabf6ff3a --- /dev/null +++ b/.changeset/sandbox-github-token-groups.md @@ -0,0 +1,5 @@ +--- +'@mastra/factory': patch +--- + +Sandboxes in a Factory with more than ten repositories can now reach all of them with `git` and `gh`. The Factory mints each sandbox token for at most ten repositories, so the sandbox now gets one token per group of ten (`GH_TOKEN`, `GH_TOKEN_2`, …). Each checkout's git credential helper uses the token that covers it, `github_refresh_token` refreshes every group, and the environment note tells the agent which variable to use for `gh` in each repository, for example `GH_TOKEN=$GH_TOKEN_2 gh pr list -R owner/repo`. Before, a Factory over ten repositories fell back to a token for the session repository only. diff --git a/mastracode/factory/src/environment/repository-access.ts b/mastracode/factory/src/environment/repository-access.ts index ea5b2e80f42..ecb8ebb3073 100644 --- a/mastracode/factory/src/environment/repository-access.ts +++ b/mastracode/factory/src/environment/repository-access.ts @@ -11,6 +11,14 @@ const REPOSITORIES_PER_TOKEN = 10; */ const GROUP_RETRY_AFTER_MS = 60_000; +/** Split repository ids into the groups one token each can name, keeping order and dropping repeats. */ +export function groupRepositoryIds(repositoryIds: readonly string[]): string[][] { + const ids = [...new Set(repositoryIds)]; + const groups: string[][] = []; + for (let i = 0; i < ids.length; i += REPOSITORIES_PER_TOKEN) groups.push(ids.slice(i, i + REPOSITORIES_PER_TOKEN)); + return groups; +} + /** * Access to each of an environment's repositories, minted a group at a time. * Asking for one repository asks for its group of up to ten, so a provider @@ -27,9 +35,7 @@ export function groupedRepositoryAccess( repositoryIds: readonly string[], now: () => number = Date.now, ): (repositoryId: string) => Promise { - const ids = [...new Set(repositoryIds)]; - const groups: string[][] = []; - for (let i = 0; i < ids.length; i += REPOSITORIES_PER_TOKEN) groups.push(ids.slice(i, i + REPOSITORIES_PER_TOKEN)); + const groups = groupRepositoryIds(repositoryIds); const skipUntil = new Map(); const pending = new Map>(); const groupAccess = (group: string[], getRepositoriesAccess: GetRepositoriesAccess) => { diff --git a/mastracode/factory/src/integrations/github/sandbox.test.ts b/mastracode/factory/src/integrations/github/sandbox.test.ts index 8de3b363865..59ad4876623 100644 --- a/mastracode/factory/src/integrations/github/sandbox.test.ts +++ b/mastracode/factory/src/integrations/github/sandbox.test.ts @@ -26,6 +26,7 @@ import { runTeardownCommand, shellQuote, SetupCommandError, + githubCredentialHelper, syncEnvironmentRepository, } from './sandbox.js'; import type { RepoMaterializeInfo } from './sandbox.js'; @@ -695,6 +696,34 @@ describe('syncEnvironmentRepository', () => { const authEnvOf = (sandbox: FakeSandbox, fragment: string) => sandbox.executions.find(execution => execution.args.join(' ').includes(fragment))?.options?.env; + it('points the checkout credential helper at the sandbox token that covers the repository', async () => { + const sandbox = new FakeSandbox(() => OK); + + await syncEnvironmentRepository(sandbox, '/workspace/docs', { ...opts, tokenEnvName: 'GH_TOKEN_2' }); + + expect(sandbox.calls).toContain( + 'git -C /workspace/docs config credential.helper !f() { GH_TOKEN="${GH_TOKEN_2:-$GH_TOKEN}" gh auth git-credential "$@"; }; f', + ); + }); + + it('installs the plain gh credential helper for repositories GH_TOKEN covers, and none for non-GitHub hosts', async () => { + const github = new FakeSandbox(() => OK); + await syncEnvironmentRepository(github, '/workspace/docs', opts); + expect(github.calls).toContain('git -C /workspace/docs config credential.helper !gh auth git-credential'); + + const gitlab = new FakeSandbox(() => OK); + await syncEnvironmentRepository(gitlab, '/workspace/docs', { + ...opts, + authUsername: 'oauth2', + tokenEnvName: 'GH_TOKEN_2', + }); + expect(gitlab.calls.join('\n')).not.toContain('config credential.helper'); + }); + + it('refuses a token variable name it would have to quote into the helper', () => { + expect(() => githubCredentialHelper('GH_TOKEN_2; rm -rf /')).toThrow(); + }); + it('resumes the session branch from the remote when the remote has it, authenticated with the repo token', async () => { const sandbox = new FakeSandbox(script => { if (script.includes('branch --show-current')) return OK; // detached template pin diff --git a/mastracode/factory/src/integrations/github/sandbox.ts b/mastracode/factory/src/integrations/github/sandbox.ts index 87cc3f76fd9..8ff776ec4bc 100644 --- a/mastracode/factory/src/integrations/github/sandbox.ts +++ b/mastracode/factory/src/integrations/github/sandbox.ts @@ -472,6 +472,18 @@ export interface SessionBranchOptions { */ const GH_CREDENTIAL_HELPER = '!gh auth git-credential'; +/** + * The git credential helper for a GitHub checkout whose repository is covered + * by a numbered group token (`GH_TOKEN_2`, ...) instead of `GH_TOKEN`. It + * falls back to `GH_TOKEN` while the group token is unset, as it is when an + * org PAT is installed. + */ +export function githubCredentialHelper(tokenEnvName = 'GH_TOKEN'): string { + if (tokenEnvName === 'GH_TOKEN') return GH_CREDENTIAL_HELPER; + if (!/^GH_TOKEN_\d+$/.test(tokenEnvName)) throw new Error(`Invalid GitHub token variable: ${tokenEnvName}`); + return `!f() { GH_TOKEN="\${${tokenEnvName}:-$GH_TOKEN}" gh auth git-credential "$@"; }; f`; +} + async function fetchStartPoint( sandbox: ExecutableSandbox, workdir: string, @@ -542,6 +554,11 @@ export interface SyncEnvironmentRepositoryOptions { repoFullName: string; cloneUrl?: string; authUsername?: string; + /** + * The sandbox variable carrying this GitHub repository's token; the checkout + * gets a credential helper reading it. Ignored when `authUsername` is set. + */ + tokenEnvName?: string; } export interface EnvironmentSyncResult { @@ -571,6 +588,19 @@ export async function syncEnvironmentRepository( const cleanCloneUrl = cloneUrl ?? cleanUrl(repoFullName); const authEnv = gitAuthenticationEnvironment(cleanCloneUrl, token, authUsername ?? 'x-access-token', 'pull-failed'); + // Raw git in this checkout (push, fetch) authenticates through gh with the + // token that covers this repository, like the session repository does. + if (!authUsername) { + const configured = await execute(sandbox, 'git', [ + '-C', + workdir, + 'config', + 'credential.helper', + githubCredentialHelper(options.tokenEnvName), + ]); + if (configured.exitCode !== 0) throw classifyGitFailure(configured, 'pull-failed'); + } + await configureGitIdentity(sandbox, workdir, options.identity ?? {}); const current = await execute(sandbox, 'git', ['-C', workdir, 'branch', '--show-current']); @@ -1175,7 +1205,9 @@ async function runLifecycleCommand( // Mask before trimming: a value with an edge newline or space would no longer match once trimmed. const output = result.stderr.trim() ? result.stderr : result.stdout; const mask = typeof options.mask === 'function' ? options.mask() : options.mask; - const detail = maskSandboxEnvValues(output, { ...mask, ...options.env }).trim().slice(-1800); + const detail = maskSandboxEnvValues(output, { ...mask, ...options.env }) + .trim() + .slice(-1800); const label = options.phase === 'setup' ? 'Setup' : 'Teardown'; throw new SetupCommandError( `${label} command failed (exit ${result.exitCode}): ${detail}`, diff --git a/mastracode/factory/src/workspace.test.ts b/mastracode/factory/src/workspace.test.ts index b2862a5f460..f55f0929c67 100644 --- a/mastracode/factory/src/workspace.test.ts +++ b/mastracode/factory/src/workspace.test.ts @@ -4523,7 +4523,7 @@ describe('factory environment sandbox context', () => { expect(lastGhToken()).toBe('repo-token-repository-1'); expect(warn).toHaveBeenCalledExactlyOnceWith( - '[Mastra Factory] GH_TOKEN covers the session repository only', + '[Mastra Factory] Sandbox GitHub tokens do not cover every environment repository', expect.objectContaining({ reason: 'provider failed to mint one token for this repository set (Error)', }), @@ -4545,10 +4545,10 @@ describe('factory environment sandbox context', () => { expect(lastGhToken()).toBe('repo-token-repository-1'); expect(warn).toHaveBeenCalledExactlyOnceWith( - '[Mastra Factory] GH_TOKEN covers the session repository only', + '[Mastra Factory] Sandbox GitHub tokens do not cover every environment repository', expect.objectContaining({ sessionId: 'session-a', - repositories: ['octocat/hello', 'octocat/docs'], + uncovered: ['octocat/docs'], reason: 'provider mints per-repository tokens only', }), ); @@ -4559,6 +4559,139 @@ describe('factory environment sandbox context', () => { warn.mockRestore(); }); + it('mints one sandbox token per ten environment repositories and points each checkout at its own', async () => { + const links = Array.from({ length: 12 }, (_, index) => ({ + id: index === 0 ? 'project-1' : `link-${index + 1}`, + repositoryId: `repository-${index + 1}`, + slug: index === 0 ? 'octocat/hello' : `octocat/repo-${index + 1}`, + position: index + 1, + inEnvironment: true, + })); + const { resolver, github } = environmentFixture({ links }); + addProject({ setupCommand: 'pnpm i' }); + addSession({ id: 'session-a', factoryProjectId: 'factory-1' }); + const requestContext = createGithubRequestContext('project-1', 'session-a'); + + const workspace = await resolver({ requestContext }); + await workspace.sandbox.getInfo(); + + const first = links.slice(0, 10).map(link => link.repositoryId); + const second = links.slice(10).map(link => link.repositoryId); + expect(mocks.getRepositoriesAccess).toHaveBeenCalledWith({ orgId: 'org-1', repositoryIds: first }); + expect(mocks.getRepositoriesAccess).toHaveBeenCalledWith({ orgId: 'org-1', repositoryIds: second }); + const env = () => { + const calls = mocks.setEnv.mock.calls; + return ( + calls[calls.length - 1]![0] as (env: Record) => Record + )({ + GH_TOKEN_3: 'stale', + }); + }; + expect(env()).toEqual({ + GH_TOKEN: `env-token-${first.join('+')}`, + GH_TOKEN_2: `env-token-${second.join('+')}`, + }); + const tokenEnvNames = Object.fromEntries( + mocks.syncEnvironmentRepository.mock.calls.map((call: unknown[]) => { + const options = call[2] as { repoFullName: string; tokenEnvName?: string }; + return [options.repoFullName, options.tokenEnvName]; + }), + ); + expect(tokenEnvNames['octocat/repo-2']).toBe('GH_TOKEN'); + expect(tokenEnvNames['octocat/repo-10']).toBe('GH_TOKEN'); + expect(tokenEnvNames['octocat/repo-11']).toBe('GH_TOKEN_2'); + expect(tokenEnvNames['octocat/repo-12']).toBe('GH_TOKEN_2'); + expect(peekSessionEnvironment('session-a')?.note).toBe( + [ + `GH_TOKEN covers octocat/hello, ${links + .slice(1, 10) + .map(link => link.slug) + .join(', ')}.`, + 'GH_TOKEN_2 covers octocat/repo-11, octocat/repo-12; run gh for these as \`GH_TOKEN=$GH_TOKEN_2 gh ...\`.', + 'git in each checkout already authenticates with the token that covers it.', + ].join(' '), + ); + + // Refresh re-mints every group, not just the session repository's. + mocks.getRepositoriesAccess.mockClear(); + const integration = github as unknown as Parameters[1]; + const refresh = createGithubSubscriptionTools(requestContext, integration).github_refresh_token!; + expect(await refresh.execute!({}, {} as never)).toEqual({ refreshed: true }); + expect(mocks.getRepositoriesAccess).toHaveBeenCalledTimes(2); + expect(env().GH_TOKEN_2).toBe(`env-token-${second.join('+')}`); + }); + + it('installs every group token before setup runs and keeps them current across resolutions', async () => { + const links = Array.from({ length: 11 }, (_, index) => ({ + id: index === 0 ? 'project-1' : `link-${index + 1}`, + repositoryId: `repository-${index + 1}`, + slug: index === 0 ? 'octocat/hello' : `octocat/repo-${index + 1}`, + position: index + 1, + inEnvironment: true, + ...(index === 10 ? { setupCommand: 'git fetch' } : {}), + })); + const { resolver, github } = environmentFixture({ links }); + addProject({ setupCommand: 'pnpm i' }); + addSession({ id: 'session-a', factoryProjectId: 'factory-1' }); + // Snapshot each install as it happens: later mints must not change what an earlier call put in. + const installed: Record[] = []; + mocks.setEnv.mockImplementation( + (update: (env: Record) => Record) => { + installed.push(update({})); + }, + ); + const originalAccess = mocks.getRepositoryAccess.getMockImplementation()!; + const originalWideAccess = mocks.getRepositoriesAccess.getMockImplementation()!; + onTestFinished(() => { + mocks.setEnv.mockReset(); + mocks.getRepositoryAccess.mockImplementation(originalAccess); + mocks.getRepositoriesAccess.mockImplementation(originalWideAccess); + }); + const applied = (index: number) => installed[index]!; + + const workspace = await resolver({ requestContext: createGithubRequestContext('project-1', 'session-a') }); + await workspace.sandbox.getInfo(); + + // Setup commands may fetch through repository 11's helper, so GH_TOKEN_2 is there first. + expect(mocks.runSetupCommand).toHaveBeenCalled(); + const firstSetup = Math.min(...mocks.runSetupCommand.mock.invocationCallOrder); + const installedBeforeSetup = mocks.setEnv.mock.calls.some( + (_, index) => mocks.setEnv.mock.invocationCallOrder[index]! < firstSetup && applied(index).GH_TOKEN_2, + ); + expect(installedBeforeSetup).toBe(true); + // Recording the environment during setup must not lose the coverage note. + expect(peekSessionEnvironment('session-a')?.note).toContain('GH_TOKEN_2 covers octocat/repo-11'); + + // A later resolution reuses the first one's injector; its refresh must + // still install the group tokens it just minted. + const laterContext = createGithubRequestContext('project-1', 'session-a'); + await resolver({ requestContext: laterContext }); + mocks.getRepositoriesAccess.mockImplementation(async ({ repositoryIds }: { repositoryIds: string[] }) => ({ + cloneUrl: 'https://github.com/octocat/hello.git', + authorization: { scheme: 'bearer' as const, token: `fresh-${repositoryIds.join('+')}` }, + })); + mocks.getRepositoryAccess.mockImplementation(async ({ repositoryId }: { repositoryId: string }) => ({ + cloneUrl: 'https://github.com/octocat/hello.git', + authorization: { scheme: 'bearer' as const, token: `fresh-${repositoryId}` }, + })); + const integration = github as unknown as Parameters[1]; + const refresh = createGithubSubscriptionTools(laterContext, integration).github_refresh_token!; + expect(await refresh.execute!({}, {} as never)).toEqual({ refreshed: true }); + expect(applied(mocks.setEnv.mock.calls.length - 1)).toEqual({ + GH_TOKEN: `fresh-${links + .slice(0, 10) + .map(link => link.repositoryId) + .join('+')}`, + GH_TOKEN_2: 'fresh-repository-11', + }); + + // An org PAT replaces the group tokens, so the note naming them goes too. + mocks.githubPat = 'ghp_org_pat'; + expect(await refresh.execute!({}, {} as never)).toEqual({ refreshed: true }); + expect(applied(mocks.setEnv.mock.calls.length - 1)).toEqual({ GH_TOKEN: 'ghp_org_pat' }); + expect(peekSessionEnvironment('session-a')?.note).toBeUndefined(); + }); + it('skips setup where the template marker matches and runs it where the marker is missing', async () => { const { resolver } = environmentFixture({ links: [twoLinks[0]!, { ...twoLinks[1]!, setupCommand: 'pnpm docs' }], diff --git a/mastracode/factory/src/workspace.ts b/mastracode/factory/src/workspace.ts index 4810c60a165..2318e9832a0 100644 --- a/mastracode/factory/src/workspace.ts +++ b/mastracode/factory/src/workspace.ts @@ -22,7 +22,7 @@ import { getFactoryAuthUserFromContext, getFactoryAuthUserId } from './auth.js'; import { REVIEW_CONTEXT } from './boards/define-board.js'; import type { RepositoryAccess, VersionControl } from './capabilities/version-control.js'; import { redactCredentials } from './environment/build.js'; -import { groupedRepositoryAccess } from './environment/repository-access.js'; +import { groupRepositoryIds, groupedRepositoryAccess } from './environment/repository-access.js'; import type { GithubIntegration } from './integrations/github/integration.js'; import { getGithubPat } from './integrations/github/pat.js'; import type { GithubPatKind } from './integrations/github/pat.js'; @@ -725,6 +725,11 @@ export function createWorkspaceFactory(options: CreateWorkspaceFactoryOptions = // path checks for it and reports its absence. type SessionSandbox = ExecutableSandbox & { setEnv?: WorkspaceSandbox['setEnv'] }; const githubTokenInjectors = new Map(); + // Per workspace: the minted group tokens beyond `GH_TOKEN` and the note + // naming which variable covers which repositories. Kept here, not per + // resolution, so an injector registered by an earlier resolution installs + // the tokens a later resolution minted. + const githubGroupTokens = new Map; note: string | null }>(); const githubTokenReconciliations = new Map>(); // Workspace identity cache: concurrent resolutions of the same session must // observe the same Workspace object even when no Mastra registry is wired @@ -831,6 +836,39 @@ export function createWorkspaceFactory(options: CreateWorkspaceFactoryOptions = : [repository.id]; // Every environment repository's access, minted in groups of ten. const repositoryAccess = groupedRepositoryAccess(sourceControl.versionControl, session.orgId, tokenRepositoryIds); + // One sandbox token per group of ten: `GH_TOKEN` covers the first group + // (the session repository's), `GH_TOKEN_2`, `GH_TOKEN_3`... the rest. + const tokenGroups = groupRepositoryIds(tokenRepositoryIds); + const groupTokenEnvName = (index: number) => (index === 0 ? 'GH_TOKEN' : `GH_TOKEN_${index + 1}`); + const tokenEnvNameFor = (repositoryId: string) => + groupTokenEnvName( + Math.max( + 0, + tokenGroups.findIndex(group => group.includes(repositoryId)), + ), + ); + const repositorySlug = (repositoryId: string) => + repositoryId === repository.id + ? repoFullName + : (environment?.repos.find(repo => repo.repositoryId === repositoryId)?.slug ?? repositoryId); + // An org PAT reaches every repository through `GH_TOKEN`, so it drops the + // group tokens and each checkout's credential helper falls back to it. + const withGithubTokens = >(env: T, token: string, pat: boolean) => ({ + ...Object.fromEntries(Object.entries(env).filter(([name]) => !/^GH_TOKEN_\d+$/.test(name))), + GH_TOKEN: token, + ...(pat ? {} : (githubGroupTokens.get(workspaceId)?.env ?? {})), + }); + // Install the credentials and the note that matches them: a PAT needs no + // note, and recording the environment drops the note, so every install + // (including a reconnect that reuses a fresh token) restores it. + const installGithubTokens = (target: SessionSandbox, token: string, pat: boolean, required: boolean) => { + if (!target.setEnv) { + if (required) throw new Error('The active sandbox provider does not support runtime GitHub token refresh.'); + return; + } + target.setEnv(env => withGithubTokens(env, token, pat)); + setSessionEnvironmentNote(session.sessionId, pat ? null : (githubGroupTokens.get(workspaceId)?.note ?? null)); + }; if (githubProvider) { registerGithubRefreshTarget(requestContext, { orgId: session.orgId, @@ -956,10 +994,7 @@ export function createWorkspaceFactory(options: CreateWorkspaceFactoryOptions = // injector, so replacing them here would reauthorize the stale // constructing context and reject the current one. existingRegistration.inject = (freshToken, pat = false) => { - if (!target.setEnv) { - throw new Error('The active sandbox provider does not support runtime GitHub token refresh.'); - } - target.setEnv(env => ({ ...env, GH_TOKEN: freshToken })); + installGithubTokens(target, freshToken, pat, true); existingRegistration.ghToken = freshToken; existingRegistration.patInstalled = pat; existingRegistration.tokenIssuedAt = Date.now(); @@ -988,13 +1023,10 @@ export function createWorkspaceFactory(options: CreateWorkspaceFactoryOptions = const patKind = await resolveGithubPatKind(); const ghCliPat = await getGithubPat(() => githubProvider.integrationStorage, session.orgId, patKind); const ghCliToken = ghCliPat ?? (await getRepositoryToken()); - target.setEnv?.(env => ({ ...env, GH_TOKEN: ghCliToken })); + installGithubTokens(target, ghCliToken, ghCliPat !== null, false); const tokenRegistration: GithubTokenRegistration = { inject: (freshToken, pat = false) => { - if (!target.setEnv) { - throw new Error('The active sandbox provider does not support runtime GitHub token refresh.'); - } - target.setEnv(env => ({ ...env, GH_TOKEN: freshToken })); + installGithubTokens(target, freshToken, pat, true); tokenRegistration.ghToken = freshToken; tokenRegistration.patInstalled = pat; tokenRegistration.tokenIssuedAt = Date.now(); @@ -1238,51 +1270,90 @@ export function createWorkspaceFactory(options: CreateWorkspaceFactoryOptions = const configDir = DEFAULT_CONFIG_DIR; const getRepositoryAccess = () => repositoryAccess(repository.id); - // Resolve the minted token `GH_TOKEN` carries. With several environment - // repositories the provider may mint one credential for all of them; when - // it cannot (no such capability, several installations, too many - // repositories) the session repository's token is used and the agent is - // told through the environment signal, so it reaches the other - // repositories through the source_control_* tools instead of raw `gh`. + // Mint one token per group of up to ten environment repositories: the + // first group's (the session repository's) is returned for `GH_TOKEN`, + // the others are kept for the workspace in `githubGroupTokens`. A group the provider cannot mint one + // credential for falls back to its first repository's own token, and the + // agent is told through the environment signal which repositories each + // variable reaches, so it uses the source_control_* tools for the rest. let tokenScopeWarned = false; - const getRepositoryToken = async (): Promise => { - if (tokenRepositoryIds.length > 1) { - let reason = 'provider mints per-repository tokens only'; - let wide: RepositoryAccess | undefined; - if (sourceControl.versionControl.getRepositoriesAccess) { - try { - wide = await sourceControl.versionControl.getRepositoriesAccess({ - orgId: session.orgId, - repositoryIds: tokenRepositoryIds, - }); - reason = 'provider cannot mint one token for this repository set'; - } catch (error) { - // A sibling repository the provider cannot grant must not stop the - // session: its own token still boots it. The provider logs the - // failure itself; only the error name travels here. - reason = `provider failed to mint one token for this repository set (${error instanceof Error ? error.name : 'error'})`; - } - } - if (wide?.authorization?.token) { - setSessionEnvironmentNote(session.sessionId, null); - return wide.authorization.token; - } - if (!tokenScopeWarned) { - tokenScopeWarned = true; - console.warn('[Mastra Factory] GH_TOKEN covers the session repository only', { - sessionId: session.sessionId, - repositories: environment?.repos.map(repo => repo.slug) ?? [repoFullName], - reason, + const mintGroupToken = async (group: string[]): Promise<{ token?: string; covered: string[]; reason?: string }> => { + let reason = 'provider mints per-repository tokens only'; + if (group.length > 1 && sourceControl.versionControl.getRepositoriesAccess) { + try { + const wide = await sourceControl.versionControl.getRepositoriesAccess({ + orgId: session.orgId, + repositoryIds: group, }); + if (wide?.authorization?.token) return { token: wide.authorization.token, covered: group }; + reason = 'provider cannot mint one token for this repository set'; + } catch (error) { + // A sibling repository the provider cannot grant must not stop the + // session: its own token still boots it. The provider logs the + // failure itself; only the error name travels here. + reason = `provider failed to mint one token for this repository set (${error instanceof Error ? error.name : 'error'})`; } - setSessionEnvironmentNote( - session.sessionId, - `GH_TOKEN covers ${repoFullName} only; use the source_control_* tools for other repositories.`, + } + const token = ( + await sourceControl.versionControl.getRepositoryAccess({ orgId: session.orgId, repositoryId: group[0]! }) + ).authorization?.token; + return { token, covered: token ? [group[0]!] : [], ...(group.length > 1 ? { reason } : {}) }; + }; + const getRepositoryToken = async (): Promise => { + const minted = await Promise.all( + tokenGroups.map(async (group, index) => { + try { + return await mintGroupToken(group); + } catch (error) { + // The session repository's group must mint; another group failing leaves it to the tools. + if (index === 0) throw error; + return { covered: [], reason: `mint failed (${error instanceof Error ? error.name : 'error'})` }; + } + }), + ); + const primary = minted[0]?.token; + if (!primary) throw new Error('Repository access did not include a bearer token for the Factory session'); + const groupEnv = Object.fromEntries( + minted.slice(1).flatMap((group, index) => (group.token ? [[groupTokenEnvName(index + 1), group.token]] : [])), + ); + const covered = new Set(minted.flatMap(group => group.covered)); + const uncovered = tokenRepositoryIds.filter(id => !covered.has(id)); + if (uncovered.length && !tokenScopeWarned) { + tokenScopeWarned = true; + console.warn('[Mastra Factory] Sandbox GitHub tokens do not cover every environment repository', { + sessionId: session.sessionId, + uncovered: uncovered.map(repositorySlug), + reason: minted.flatMap(group => (group.reason ? [group.reason] : [])).join('; '), + }); + } + githubGroupTokens.set(workspaceId, { env: groupEnv, note: githubTokenNote(minted, uncovered) }); + return primary; + }; + // Which variable reaches which repositories, when it is not simply + // `GH_TOKEN` for all of them. + const githubTokenNote = (minted: { token?: string; covered: string[] }[], uncovered: string[]): string | null => { + if (minted.length === 1) { + return uncovered.length + ? `GH_TOKEN covers ${repoFullName} only; use the source_control_* tools for other repositories.` + : null; + } + const lines = minted.flatMap((group, index) => { + if (!group.token || !group.covered.length) return []; + const name = groupTokenEnvName(index); + const slugs = group.covered.map(repositorySlug).join(', '); + return [ + index === 0 + ? `GH_TOKEN covers ${slugs}.` + : `${name} covers ${slugs}; run gh for these as \`GH_TOKEN=$${name} gh ...\`.`, + ]; + }); + lines.push('git in each checkout already authenticates with the token that covers it.'); + if (uncovered.length) { + lines.push( + `No sandbox token covers ${uncovered.map(repositorySlug).join(', ')}; use the source_control_* tools for them.`, ); } - const token = (await getRepositoryAccess()).authorization?.token; - if (!token) throw new Error('Repository access did not include a bearer token for the Factory session'); - return token; + return lines.join(' '); }; const resolveGithubPatKind = async (): Promise => { if (!workItems) return 'default'; @@ -1396,6 +1467,7 @@ export function createWorkspaceFactory(options: CreateWorkspaceFactoryOptions = } if (evicted && githubTokenInjectors.get(workspaceId) === registered) { githubTokenInjectors.delete(workspaceId); + githubGroupTokens.delete(workspaceId); constructedWorkspaces.delete(workspaceId); skillCacheState.delete(workspaceId); } @@ -1501,9 +1573,11 @@ export function createWorkspaceFactory(options: CreateWorkspaceFactoryOptions = // source-control providers. if (githubProvider) { const setupPatKind = await resolveGithubPatKind(); - const setupGhToken = - (await getGithubPat(() => githubProvider.integrationStorage, session.orgId, setupPatKind)) ?? token; - target.setEnv?.(env => ({ ...env, GH_TOKEN: setupGhToken })); + const setupPat = await getGithubPat(() => githubProvider.integrationStorage, session.orgId, setupPatKind); + // Setup commands in any environment repository may fetch through its + // credential helper, so mint every group's token before they run. + const setupGhToken = setupPat ?? (tokenGroups.length > 1 ? await getRepositoryToken() : token); + installGithubTokens(target, setupGhToken, setupPat !== null, false); } await materializeRepo({ row: { id: session.id, sandboxWorkdir: workdir, materializedAt: session.materializedAt }, @@ -1683,6 +1757,7 @@ export function createWorkspaceFactory(options: CreateWorkspaceFactoryOptions = repoFullName: repo.slug, cloneUrl: access.cloneUrl, authUsername: access.authorization?.username, + tokenEnvName: tokenEnvNameFor(repo.repositoryId), }), ); state.branch = synced.branch; @@ -1862,6 +1937,7 @@ export function createWorkspaceFactory(options: CreateWorkspaceFactoryOptions = workspaceGeneration, async () => { githubTokenInjectors.delete(workspaceId); + githubGroupTokens.delete(workspaceId); constructedWorkspaces.delete(workspaceId); skillCacheState.delete(workspaceId); skillReviewChecks.delete(workspaceId); From 57c921b7bc91853893fed2bcce9df5bdc7a53b8a Mon Sep 17 00:00:00 2001 From: "dane-ai-mastra[bot]" <199668360+dane-ai-mastra[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 21:28:35 +0000 Subject: [PATCH 002/239] chore: version - enter prerelease mode --- .changeset/pre.json | 200 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 .changeset/pre.json diff --git a/.changeset/pre.json b/.changeset/pre.json new file mode 100644 index 00000000000..f2af00f94ff --- /dev/null +++ b/.changeset/pre.json @@ -0,0 +1,200 @@ +{ + "mode": "pre", + "tag": "alpha", + "initialVersions": { + "@mastra/acp": "0.4.4", + "@mastra/claude": "0.3.4", + "@mastra/cursor": "0.3.4", + "@mastra/openai": "1.1.4", + "@mastra/auth-auth0": "1.3.0", + "@mastra/auth-better-auth": "1.1.11", + "@mastra/auth-clerk": "1.4.0", + "@mastra/auth-cloud": "1.2.9", + "@mastra/auth-firebase": "1.1.5", + "@mastra/auth-google": "0.1.7", + "@mastra/auth-neon": "0.3.6", + "@mastra/auth-okta": "0.3.0", + "@mastra/auth-studio": "1.4.0", + "@mastra/auth-supabase": "1.2.0", + "@mastra/auth-workos": "1.6.9", + "@internal/browser-test-utils": "0.0.68", + "@mastra/agent-browser": "0.6.0", + "@mastra/browser-viewer": "0.3.0", + "@mastra/browser-firecrawl": "0.3.0", + "@mastra/stagehand": "0.4.0", + "@mastra/discord": "1.3.4", + "@mastra/slack": "1.9.0", + "@mastra/teams": "0.1.5", + "@mastra/telegram": "0.2.5", + "@mastra/ai-sdk": "1.12.0", + "@mastra/client-js": "1.60.0", + "@mastra/react": "1.15.0", + "@mastra/isolated-vm": "0.1.4", + "@mastra/quickjs": "0.1.5", + "@mastra/deployer-cloud": "1.83.0", + "@mastra/deployer-cloudflare": "1.2.42", + "@mastra/deployer-netlify": "1.2.42", + "@mastra/deployer-sandbox": "0.3.27", + "@mastra/deployer-vercel": "1.2.42", + "mastra-docs": "0.0.93", + "@internal/client-js-test-utils": "1.0.1", + "client-js-e2e-tests-zod-v3": "1.0.1", + "client-js-e2e-tests-zod-v4": "1.0.1", + "workspace-compat-e2e-test": "0.0.95", + "@mastra/voyageai": "0.4.3", + "@mastra/longmemeval": "1.1.42", + "@mastra/brightdata": "0.3.2", + "@mastra/livekit": "0.5.3", + "@mastra/opencode": "0.1.42", + "@mastra/parallel": "0.1.5", + "@mastra/perplexity": "0.2.2", + "@mastra/tavily": "1.1.3", + "@mastra/factory": "0.28.0", + "@internal/factory-ui": "0.0.0", + "create-factory": "0.4.3", + "@mastra/code-sdk": "1.19.0", + "mastracode": "0.50.0", + "@observability/test-utils": "0.1.1", + "@mastra/arize": "1.3.30", + "@mastra/arthur": "0.4.30", + "@mastra/braintrust": "1.3.27", + "@mastra/datadog": "1.4.22", + "@mastra/deepeval": "0.1.24", + "@mastra/laminar": "1.3.32", + "@mastra/langfuse": "1.6.6", + "@mastra/langsmith": "1.4.3", + "@mastra/observability": "1.24.0", + "@mastra/otel-bridge": "1.5.22", + "@mastra/otel-exporter": "1.5.2", + "@mastra/posthog": "1.4.7", + "@mastra/sentry": "1.2.32", + "@internal/changeset-cli": "0.0.103", + "@internal/lint": "0.0.149", + "@internal/external-types": "0.0.99", + "@internal/core": "0.1.4", + "@internal/auth": "0.0.37", + "@internal/deployer": "0.0.2", + "@internal/find-workspaces": "0.0.4", + "@internal/voice": "0.0.45", + "@internal/workspace": "0.0.21", + "@internal/llm-recorder": "0.0.85", + "@internal/test-utils": "0.0.85", + "@internal/types-builder": "0.0.124", + "@internal/ai-sdk-v4": "0.0.96", + "@internal/ai-sdk-v5": "0.0.96", + "@internal/ai-v6": "0.0.96", + "@internal/ai-v7": "0.0.96", + "@mastra/agent-builder": "1.2.1", + "@mastra/auth": "1.2.0", + "mastra": "1.39.0", + "@mastra/codemod": "1.1.8", + "@mastra/connect": "1.4.0", + "@mastra/core": "1.83.0", + "create-mastra": "1.39.0", + "@mastra/deployer": "1.83.0", + "@mastra/editor": "0.17.1", + "@mastra/evals": "1.10.11", + "@mastra/fastembed": "1.3.7", + "@mastra/loggers": "1.3.10", + "@mastra/mcp": "2.9.0", + "@mastra/mcp-apps-components": "0.1.0", + "@mastra/mcp-docs-server": "1.3.13", + "@mastra/mcp-registry-registry": "1.1.7", + "@mastra/memory": "1.41.1", + "@internal/playground": "1.39.0", + "@mastra/playground-ui": "69.0.0", + "@mastra/rag": "2.8.0", + "@mastra/schema-compat": "1.4.0", + "@mastra/server": "1.83.0", + "@mastra/google-cloud-pubsub": "1.1.7", + "@mastra/redis-streams": "0.8.1", + "@mastra/valkey-streams": "0.6.2", + "@mastra/elysia": "0.1.23", + "@mastra/express": "1.5.27", + "@mastra/fastify": "1.5.27", + "@mastra/hono": "1.7.25", + "@mastra/koa": "1.7.27", + "@mastra/nestjs": "0.3.0", + "@mastra/next": "0.2.41", + "@mastra/server-adapters-test-suite": "0.3.0", + "@mastra/tanstack-start": "0.2.41", + "@mastra/github-signals": "0.5.2", + "@mastra/ring-signals": "0.1.0", + "@internal/storage-test-utils": "0.0.145", + "@mastra/astra": "1.1.3", + "@mastra/azure-ai-search": "0.1.2", + "@mastra/chroma": "1.1.5", + "@mastra/clickhouse": "1.30.0", + "@mastra/cloudflare": "1.8.0", + "@mastra/cloudflare-d1": "1.5.0", + "@mastra/convex": "1.9.0", + "@mastra/couchbase": "1.1.4", + "@mastra/dsql": "1.5.7", + "@mastra/duckdb": "1.19.0", + "@mastra/dynamodb": "1.5.1", + "@mastra/elasticsearch": "1.4.6", + "@mastra/lance": "1.6.1", + "@mastra/libsql": "1.30.0", + "@mastra/mongodb": "1.27.0", + "@mastra/mssql": "1.11.1", + "@mastra/mysql": "0.17.0", + "@mastra/opensearch": "1.1.4", + "@mastra/oracledb": "0.5.6", + "@mastra/pg": "1.36.0", + "@mastra/pinecone": "1.1.3", + "@mastra/qdrant": "1.1.6", + "@mastra/redis": "1.4.13", + "@mastra/s3vectors": "1.1.5", + "@mastra/spanner": "1.12.0", + "@mastra/turbopuffer": "1.2.3", + "@mastra/turso": "0.1.21", + "@mastra/upstash": "1.6.1", + "@mastra/valkey": "0.2.9", + "@mastra/vectorize": "1.1.5", + "@mastra/weaviate": "0.1.4", + "@mastra/voice-aws-nova-sonic": "0.2.6", + "@mastra/voice-azure": "0.12.3", + "@mastra/voice-cloudflare": "0.13.4", + "@mastra/voice-deepgram": "0.13.4", + "@mastra/voice-elevenlabs": "0.13.3", + "@mastra/voice-gladia": "0.13.3", + "@mastra/voice-google": "0.14.5", + "@mastra/voice-google-gemini-live": "0.14.19", + "@mastra/voice-inworld": "0.4.6", + "@mastra/voice-mistral": "0.1.3", + "@mastra/voice-modelslab": "0.2.3", + "@mastra/voice-murf": "0.13.3", + "@mastra/voice-openai": "0.13.4", + "@mastra/voice-openai-realtime": "0.14.9", + "@mastra/voice-playai": "0.13.3", + "@mastra/voice-sarvam": "1.1.4", + "@mastra/voice-speechify": "0.15.0", + "@mastra/voice-xai-realtime": "0.2.18", + "@internal/workflow-test-utils": "0.0.31", + "@mastra/inngest": "1.11.2", + "@mastra/temporal": "0.6.0", + "@internal/workspace-test-utils": "0.0.93", + "@mastra/agentcore": "0.5.3", + "@mastra/agentfs": "0.2.3", + "@mastra/apple-container": "0.5.2", + "@mastra/archil": "0.3.2", + "@mastra/azure": "0.3.3", + "@mastra/blaxel": "0.10.2", + "@mastra/cloudflare-sandbox": "0.5.4", + "@mastra/daytona": "0.11.5", + "@mastra/docker": "0.14.0", + "@mastra/e2b": "0.17.0", + "@mastra/e2b-desktop": "0.1.13", + "@mastra/files-sdk": "0.3.3", + "@mastra/gcs": "0.3.6", + "@mastra/google-drive": "0.2.4", + "@mastra/mesa": "0.3.3", + "@mastra/modal": "0.7.4", + "@mastra/platform-workspace": "1.13.0", + "@mastra/railway": "0.10.2", + "@mastra/s3": "0.6.5", + "@mastra/sprites": "0.1.2", + "@mastra/vercel": "1.6.3" + }, + "changesets": [] +} From 28e243f638750d514cc41bc0a052a0b09883f3e2 Mon Sep 17 00:00:00 2001 From: Damien Schneider <74979845+damien-schneider@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:33:10 -0800 Subject: [PATCH 003/239] feat(factory): read a board by phase, searched and filtered on the server (#30177) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **─────── TLDR ───────** > A Factory board can now be read one page of each phase at a time, searched and filtered on the server, instead of downloading every card of the project. The board page downloads the whole project to draw a few dozen cards per phase, then searches, filters, orders and counts them in the browser. These two reads do that work on the server: one names the first cards of each phase and counts the rest, the other lists what the filter menus offer. Nothing calls them yet; the board page moves onto them in the next PR. ### Behavior changed `GET …/boards/:boardKey/phases`   ├─ **new** — per phase, `total` and its first 50 cards as `{ id, version }`   ├─ **new** — `q`, `label`, `source` or a people filter keep the matching cards only   └─ **new** — `cards=true` also sends the body of every named card, each with its `version` the same read with `window=:`   ├─ **new** — lists that phase deeper, the others stay at `limit`   └─ **new** — a window for a phase the board no longer has is ignored the same read with `item=`   ├─ **new** — names the card, its position in each phase, and its body   └─ **new** — no phase is listed deeper for it, however old the card the same read sent again with `If-None-Match`   └─ **new** — 304 unless a named card's body, an order or a total changed `GET …/work-items/filter-options`   └─ **new** — labels, the people sources name, the Factory users who acted The whole-board list, its `since` read, the starters and the agent tools answer as before, except that `?workItemId=` now sends each card's `version` too. `since` loses its last reader when the next PR merges, and a follow-up removes it. ### Shape changed | | | | |---|---|---| | **+** | `boardPhases(list, board, view, userId, version)` | pure, so the browser's tests can run it as the server | | **+** | `cardFacts(card)` | what search and filters read, once per card version | | **+** | `sendRevalidated` · `sendJson` · `namedBody` | the list route's ETag and gzip answer, now shared | | **~** | `workItemNumber` | moved to `work-items/card-number.ts`, 7 importers | | **~** | `sourceFacts` | merged into `sourceMetadata`: one reading of a card's source | | **~** | `searchWords` · `hasEveryWord` | moved out of `routes/`, importable by the browser | - `mastracode/factory/src/work-items/` - └─ `board-phases.ts` — place, order, filter, count - └─ `board-filter-options.ts` - └─ `card-facts.ts` · `card-people.ts` · `card-source-filters.ts` · `card-labels.ts` - └─ `card-search-text.ts` · `search-words.ts` · `card-number.ts` · `list-related-cards.ts` — moved here - `mastracode/factory/src/routes/` - └─ `contracts.ts` — both contracts - └─ `work-items.ts` — both handlers what the next PR builds on     `GET …/boards/:boardKey/phases` · `GET …/work-items/filter-options` · `mastra api factory board phases` · `mastra api factory work-item filter-options` ### Decisions - **a version per card, not a time cursor** — `version` is a hash of the body sent, so a reader rereads by id whatever differs; `changedAt` missed two kinds of change. - **`q` needs every word** — the rule the agents' search already follows; the board's phrase match goes with the next PR. - **filters read the stored card** — `worked` is its creator, movers and session starters, and a live intake candidate's labels and people are not seen until the next sync. The two changes `changedAt` missed: a source sync landing in the same millisecond as another write, and a Review card shown as a Work card once the Review board closes, which writes nothing to it. Related cards are capped too: each named card brings the first `limit` of its related cards, and `relatedTotal` counts them all. ### Gain Gzipped bytes, measured in-process on a synthetic board with 3 KB of description per card: | read | 2,500 cards | 10,000 cards | |---|---|---| | whole board, as today | 2,859,778 | 11,440,412 | | phases with `cards=true` | 414,278 | 414,070 | | phases, each later read | 8,930 | 8,921 | | phases, nothing shown changed | 0 (304) | 0 (304) | | one changed card by id | 1,736 | 1,767 | The table predates `version`. A hash compresses worse than a timestamp: on a second harness, 300 names went from 3.3 KB to 7.8 KB gzipped, so expect the "each later read" row about 4.5 KB higher. A link to the oldest Done card of 10,000 used to send 8,250 bodies; it now sends the first page plus one. A 304 with `cards=true` over 300 cards takes 0.23 ms, because it hashes the names and never serializes the bodies. After one card changes, the server rebuilds the phase index in 2.3 ms at 2,500 cards and 5.2 ms at 10,000, where serializing and gzipping the whole board takes 188 ms and 747 ms. A search's first read takes 13 ms and 23 ms. Unchanged: the server keeps the project's cards in memory and, after each change, reads what changed and re-sorts the list. That refresh takes 61 ms and 254 ms in this harness, on in-memory storage; paging in SQL is a later step. ### Not verified - [ ] both reads against Postgres on a real project — measured on in-memory storage only - [ ] `source=pull-request` for an issue card with a pull request attached, through the route — only the rule is unit-tested - [ ] the Gain table with `version` in the names — the first harness was not rerun - [ ] why `attention › tracks read and archived failure occurrences across retries` fails some runs on Postgres — 3 of 6 at the previous head too, not touched here --- > ██████████████████ **tests** `+1147` — 45% of the additions > ███████████████ **source** `+940 −109` > ███████ **generated** `+418` — CLI route metadata > █ **changeset** `+21` > █ **docs** `+2` --------- Co-authored-by: Damien Schneider Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/perky-colts-glow.md | 10 + .changeset/polite-pianos-show.md | 11 + mastracode/factory/README.md | 2 + mastracode/factory/src/mcp/routes.ts | 2 +- .../factory/src/routes/board-snapshot.ts | 25 +- mastracode/factory/src/routes/contracts.ts | 159 ++++- .../factory/src/routes/work-item-selection.ts | 24 +- .../factory/src/routes/work-item-starters.ts | 20 +- .../factory/src/routes/work-items.test.ts | 624 ++++++++++++++++++ mastracode/factory/src/routes/work-items.ts | 166 ++++- .../factory/src/tools/messaging-tools.ts | 2 +- mastracode/factory/src/tools/read-tools.ts | 12 +- mastracode/factory/src/tools/reports.ts | 2 +- mastracode/factory/src/tools/session-tools.ts | 3 +- mastracode/factory/src/tools/side-sessions.ts | 2 +- .../factory/src/tools/work-item-tools.ts | 11 +- .../src/work-items/board-filter-options.ts | 36 + .../src/work-items/board-phases.test.ts | 298 +++++++++ .../factory/src/work-items/board-phases.ts | 231 +++++++ .../factory/src/work-items/card-facts.ts | 88 +++ .../factory/src/work-items/card-labels.ts | 14 + .../factory/src/work-items/card-number.ts | 18 + .../src/work-items/card-people.test.ts | 132 ++++ .../factory/src/work-items/card-people.ts | 119 ++++ .../src/work-items/card-search-text.ts | 11 + .../work-items/card-source-filters.test.ts | 91 +++ .../src/work-items/card-source-filters.ts | 46 ++ .../src/work-items/create-work-item.ts | 8 +- .../src/work-items/list-related-cards.ts | 26 + .../factory/src/work-items/search-words.ts | 9 + .../cli/src/commands/api/descriptors.test.ts | 2 + .../api/factory-route-metadata.generated.ts | 418 ++++++++++++ packages/cli/src/commands/api/index.ts | 15 + 33 files changed, 2528 insertions(+), 109 deletions(-) create mode 100644 .changeset/perky-colts-glow.md create mode 100644 .changeset/polite-pianos-show.md create mode 100644 mastracode/factory/src/work-items/board-filter-options.ts create mode 100644 mastracode/factory/src/work-items/board-phases.test.ts create mode 100644 mastracode/factory/src/work-items/board-phases.ts create mode 100644 mastracode/factory/src/work-items/card-facts.ts create mode 100644 mastracode/factory/src/work-items/card-labels.ts create mode 100644 mastracode/factory/src/work-items/card-number.ts create mode 100644 mastracode/factory/src/work-items/card-people.test.ts create mode 100644 mastracode/factory/src/work-items/card-people.ts create mode 100644 mastracode/factory/src/work-items/card-search-text.ts create mode 100644 mastracode/factory/src/work-items/card-source-filters.test.ts create mode 100644 mastracode/factory/src/work-items/card-source-filters.ts create mode 100644 mastracode/factory/src/work-items/list-related-cards.ts create mode 100644 mastracode/factory/src/work-items/search-words.ts diff --git a/.changeset/perky-colts-glow.md b/.changeset/perky-colts-glow.md new file mode 100644 index 00000000000..8d31c8a2063 --- /dev/null +++ b/.changeset/perky-colts-glow.md @@ -0,0 +1,10 @@ +--- +'mastra': patch +--- + +Added `mastra api factory board phases` and `mastra api factory work-item filter-options`, which read the first cards under each phase of a Factory board and the labels and people it can be filtered by. + +```bash +mastra api factory board phases work '{"label":["bug"],"limit":10}' +mastra api factory work-item filter-options +``` diff --git a/.changeset/polite-pianos-show.md b/.changeset/polite-pianos-show.md new file mode 100644 index 00000000000..246f2a23c0a --- /dev/null +++ b/.changeset/polite-pianos-show.md @@ -0,0 +1,11 @@ +--- +'@mastra/factory': minor +--- + +Added two reads that serve a Factory board without sending every card. `GET /web/factory/projects/:id/boards/:boardKey/phases` returns, for each phase of the board, how many cards it holds and the first of them in the order asked, after the search and filters given. `GET /web/factory/projects/:id/work-items/filter-options` returns the labels and people the board can be filtered by. `item=` also answers for one card and its place in each phase, however deep it lies, without listing the phase down to it. Each card is named with a `version` of its body, which `?workItemId=` also sends, so a reader keeps the bodies it holds and reads only the ones that changed. + +```ts +const res = await fetch(`/web/factory/projects/${projectId}/boards/work/phases?label=bug&limit=10&cards=true`); +const { phases, matchingTotal, boardTotal, workItems } = await res.json(); +// phases: [{ phase: "intake", total: 42, cards: [{ id, version }, …] }, …] +``` diff --git a/mastracode/factory/README.md b/mastracode/factory/README.md index f7c03999ced..4d4497da52c 100644 --- a/mastracode/factory/README.md +++ b/mastracode/factory/README.md @@ -64,6 +64,8 @@ The whole-board listing also returns a `cursor`, and each card carries `changedA Two reads answer questions about a project's cards without listing them. `GET /web/factory/projects/:id/work-items/starters` counts the cards on the default board that each new-session starter would act on: cards whose run failed, pull requests with changes requested, pull requests waiting for review (with when the oldest was opened), triaged cards waiting on a person, untriaged cards, bugs with no plan, the label with the most cards not started, and stale pull requests. Failed runs are read from the 50 newest run decisions, as on the cards. `GET /web/factory/projects/:id/work-items/activity?since=` returns how many cards the project has, and when cards were created and completed from `since` on; a missing or malformed `since` is a 400. Its answer carries an `ETag`: ask again for the same `since` with `If-None-Match`, and an answer that did not change comes back as a 304 with no body. +Two more reads serve a board without sending every card. `GET /web/factory/projects/:id/boards/:boardKey/phases` returns one entry per phase of the board in `phases`, in the board's order: `phase` is its id, `total` counts the cards in it, and `cards` names the first of them as `{ id, version }`. `version` names the card's body: it is another value whenever anything in the body is, including a change that leaves `changedAt` as it was. `limit` sets how many each phase names (50 unless given, 200 at most), `window=:` (repeatable) names more cards of one phase, and `item=` asks for one card wherever it lies: the answer names it in `item` as `{ id, version, places }`, where `places` gives each phase the view lists it under and its `position` there (how many cards the phase lists before it), and `cards=true` sends its body. No phase names more cards for it, so the answer is the same size for the oldest card of a phase as for the newest. `places` is empty when the search or filters leave the card out, and `item` is absent when the board does not hold the card. `sort` is `recent` (latest entry into the phase first, the default), `recent-mine` (the cards the signed-in user last moved into the phase first), `created-newest` or `created-oldest`. `q` keeps the cards whose title, key, number or source id contains every word in it; `label`, `source`, `linearProject`, `teammate`, `author`, `assignee`, `reviewer` and `worked` (all repeatable) keep the cards matching every field given. `boardTotal` counts the board's cards whatever the search and filters, `matchingTotal` the cards matching them, a card in two phases once. `related` names the cards related to a named card that no phase names, the first `limit` of each card's, and `relatedTotal` counts them all, and `runningSessionIds` and `parkedSessionIds` cover the named cards. Pass `cards=true` to also receive the body of every named card in `workItems`, each with its `version`; without it, read the cards whose `version` differs from the copy you kept with `GET /web/factory/projects/:id/work-items?workItemId=`, which sends each card with its `version` too. A card in none of the board's phases is counted in the first one. A malformed parameter is a 400 `invalid_phases_query`; a board the project doesn't have is a 404; a `window` for a phase the board doesn't have is ignored. `GET /web/factory/projects/:id/work-items/filter-options` returns what a board can be filtered by, over every card of the project: `labels`, sorted; `people`, each person a source names as author, assignee or requested reviewer, as `{ id, name, source }`; and `actorIds`, the Factory users who filed, moved or started a card. Both answers carry an `ETag`; send it back as `If-None-Match` and an unchanged answer is a 304. + #### Migration and dry run Factory keeps the legacy `work_items` table and copies each card into the new tables. Before it starts serving, it copies only open cards. Done and canceled cards are copied in the background afterwards and appear on the board shortly after startup. While that runs, opening a card, or receiving a Linear, Jira, GitHub, GitLab, or incident.io event for it, copies that card on demand, so a reopened issue keeps its original card. Board lists, such as the Done column, fill in as the background copy progresses. diff --git a/mastracode/factory/src/mcp/routes.ts b/mastracode/factory/src/mcp/routes.ts index 48dd3269aa0..18abc9a9f8d 100644 --- a/mastracode/factory/src/mcp/routes.ts +++ b/mastracode/factory/src/mcp/routes.ts @@ -12,7 +12,6 @@ import { z } from 'zod'; import { getFactoryAuthUser } from '../auth.js'; import { PLATFORM_AUTH_PROVIDER } from '../platform-auth-host.js'; import type { RouteAuth } from '../routes/route.js'; -import { hasEveryWord, searchWords } from '../routes/work-item-selection.js'; import { ensureFactorySourceSession, FactorySourceSessionResolutionError } from '../session/factory-session.js'; import { auditActorProfile } from '../storage/domains/audit/base.js'; import type { FactoryProjectsStorage } from '../storage/domains/projects/base.js'; @@ -20,6 +19,7 @@ import type { SourceControlStorageHandle } from '../storage/domains/source-contr import { FACTORY_TOOL_ANNOTATIONS } from '../tools/annotations.js'; import { createFactoryTools } from '../tools/index.js'; import type { FactoryToolDependencies, FactoryToolScope } from '../tools/index.js'; +import { hasEveryWord, searchWords } from '../work-items/search-words.js'; import { propagateClientDisconnect } from './disconnect.js'; import { factoryActivityEvent } from './events.js'; diff --git a/mastracode/factory/src/routes/board-snapshot.ts b/mastracode/factory/src/routes/board-snapshot.ts index bba70d434a3..e8a5f7a2687 100644 --- a/mastracode/factory/src/routes/board-snapshot.ts +++ b/mastracode/factory/src/routes/board-snapshot.ts @@ -66,9 +66,27 @@ export function movedBody(body: unknown): Pick { +export function hashedBody(body: unknown): BoardSnapshot { const json = JSON.stringify(body); - return { etag: `W/"${sha1(json)}"`, json }; + return { etag: `W/"${sha1(json)}"`, json, gzipped: () => gzip(json) }; +} + +/** + * An answer whose `names` hold the version of every card body `bodies` adds: its ETag is a hash of + * `names`, and the bodies are serialized only for a reader that does not hold the answer. + */ +export function namedBody(names: object, bodies?: () => object): BoardSnapshot { + const named = JSON.stringify(names); + let whole: string | undefined; + const json = () => (whole ??= bodies ? JSON.stringify({ ...names, ...bodies() }) : named); + return { + // An answer with bodies is not one a reader of the names alone holds. + etag: `W/"${sha1(named)}${bodies ? '.bodies' : ''}"`, + get json() { + return json(); + }, + gzipped: () => gzip(json()), + }; } const checks = new WeakMap(); @@ -106,7 +124,8 @@ function snapshot( return cards.latest; } -function sha1(text: string): string { +/** Names a text: a reader holding another text holds another name. */ +export function sha1(text: string): string { return createHash('sha1').update(text).digest('base64url'); } diff --git a/mastracode/factory/src/routes/contracts.ts b/mastracode/factory/src/routes/contracts.ts index fc833126874..3f8cdada774 100644 --- a/mastracode/factory/src/routes/contracts.ts +++ b/mastracode/factory/src/routes/contracts.ts @@ -91,12 +91,12 @@ const storedBoardResponseSchema = z.object({ canEdit: z.boolean().optional(), }); const intakeRoutePathSchema = z.object({ id: uuidSchema, routeId: uuidSchema }); -const intakeRouteIdentifierSchema = z.string().max(MAX_BOARD_IDENTIFIER_LENGTH).regex(BOARD_IDENTIFIER_RE); +const boardIdentifierSchema = z.string().max(MAX_BOARD_IDENTIFIER_LENGTH).regex(BOARD_IDENTIFIER_RE); const intakeRouteTargetSchema = z .object({ - boardKey: intakeRouteIdentifierSchema, + boardKey: boardIdentifierSchema, /** Unset lands the card in the board's first phase. */ - phaseKey: intakeRouteIdentifierSchema.nullable().optional(), + phaseKey: boardIdentifierSchema.nullable().optional(), /** * File a pull request on the card of the issue it closes (on `boardKey`) instead of a new card; * that card moves to `phaseKey` when its board allows it. Matches no other arrival. @@ -480,7 +480,10 @@ const workItemListQuerySchema = z limit: boundedLimitSchema(20, 50), /** Repeatable. Narrows the list to the cards filed from these sources, each named by its id or its URL. */ source: z.array(z.string().min(1).max(512)).min(1).max(100).optional(), - /** Repeatable. Narrows the list to the cards with these ids; an id no card has lists nothing. */ + /** + * Repeatable. Narrows the list to the cards with these ids; an id no card has lists nothing. + * Each card comes with the `version` the phases read names it by. + */ workItemId: z.array(uuidSchema).min(1).max(100).optional(), /** * The `cursor` of the whole board this reader holds: the answer is then what moved since. One @@ -544,6 +547,139 @@ export const workItemActivityResponseSchema = z.object({ doneAt: z.array(z.string()), }); +export const BOARD_PHASES_SORTS = ['recent', 'recent-mine', 'created-newest', 'created-oldest'] as const; + +/** Repeatable. The values picked for one filter: a card matches on any of them, and none picks every card. */ +const pickedValuesSchema = z + .array(z.string().min(1).max(512)) + .max(100) + .default([]) + .transform(values => new Set(values)); + +/** `:`: how many cards of one phase to list. */ +const phaseWindowSchema = z + .string() + .transform((entry): [phase: string, count: string] => { + const colon = entry.lastIndexOf(':'); + return [entry.slice(0, Math.max(colon, 0)), entry.slice(colon + 1)]; + }) + .pipe( + z.tuple([ + boardIdentifierSchema, + z + .string() + .regex(/^[1-9]\d{0,5}$/) + .transform(Number), + ]), + ); + +/** One view of a board: its order, its search and filters, and how deep each phase is listed. */ +export const boardPhasesQuerySchema = z.object({ + /** `recent-mine` puts the cards the signed-in user last moved into the phase before the others. */ + sort: z.enum(BOARD_PHASES_SORTS).default('recent'), + /** Words that must all be in the card's title, key, number or source id. */ + q: z.string().max(200).optional(), + /** A provider (`github`, `linear`, `manual`…), or `pull-request` for every card that has one. */ + source: pickedValuesSchema, + /** Linear project ids. Picked without `source`, they keep Linear cards only. */ + linearProject: pickedValuesSchema, + /** A card matches when it carries every one of them. */ + label: pickedValuesSchema, + /** Participant ids (`github:octocat`, `factory:`) related to the card in any way. */ + teammate: pickedValuesSchema, + author: pickedValuesSchema, + assignee: pickedValuesSchema, + reviewer: pickedValuesSchema, + /** Factory users who created the card, moved it or started a session on it. */ + worked: pickedValuesSchema, + /** How many cards each phase lists. */ + limit: boundedLimitSchema(50, 200), + /** + * Repeatable `:`: lists that phase's first `count` cards instead of `limit`. + * One for a phase the board does not have is ignored. + */ + window: z + .array(phaseWindowSchema) + .max(64) + .default([]) + .refine(windows => new Set(windows.map(([phase]) => phase)).size === windows.length, { + message: 'Send one window per phase', + }) + .transform(windows => new Map(windows)), + /** + * A card to answer for wherever it lies: the answer names it with its place in each phase, and + * `cards=true` sends its body. No phase is listed deeper for it. + */ + item: uuidSchema.optional(), + /** `true` also sends the body of every card the answer names. */ + cards: z.enum(['true']).optional(), +}); + +/** + * Names a card and the body the answer was read from. `version` is another value whenever any of + * the body is, so a reader that holds the card at this version holds this body. + */ +const cardStampSchema = z.object({ id: z.string(), version: z.string() }); + +export const boardPhasesResponseSchema = z.object({ + /** The board's phases in declaration order. */ + phases: z.array( + z.object({ + phase: z.string(), + /** Cards of this phase that match the view. */ + total: countSchema, + /** The first of them in the view's order: what the reader shows. */ + cards: z.array(cardStampSchema), + }), + ), + /** With `item`: the asked card, when the board holds it. */ + item: cardStampSchema + .extend({ + /** + * Each phase the view lists the card under, and how many cards it lists before it there. + * Empty when the search or filters leave the card out. + */ + places: z.array(z.object({ phase: z.string(), position: countSchema })), + }) + .optional(), + /** + * Cards related to a listed card or to the asked one that no phase lists: the first `limit` of + * each card's, in the board's order. + */ + related: z.array(cardStampSchema), + /** How many such cards there are, named in `related` or not. */ + relatedTotal: countSchema, + /** Cards of the board, whatever the search and filters. */ + boardTotal: countSchema, + /** Cards of the board that match the view, each counted once: a card in two phases is one. */ + matchingTotal: countSchema, + /** With `cards=true`: the body of every card named in `phases`, `item` and `related`, each with its `version`. */ + workItems: z.array(cardSchema.extend({ version: z.string() })).optional(), + /** Among the named cards. */ + runningSessionIds: z.array(z.string()), + parkedSessionIds: z.array(z.string()), +}); + +/** What the board's filter menus offer, read over every card of the project. */ +export const workItemFilterOptionsResponseSchema = z.object({ + /** Every label on a card, sorted. */ + labels: z.array(z.string()), + /** The people the cards' sources name, sorted by name. `id` is what a people filter sends. */ + people: z.array( + z.object({ + id: z.string(), + name: z.string(), + source: z.enum(['github', 'gitlab', 'linear', 'jira', 'incidentio']), + }), + ), + /** The Factory users who created a card, moved one or started a session on one, sorted. */ + actorIds: z.array(z.string()), +}); + +export type BoardPhasesQuery = z.output; +export type BoardPhasesResponse = z.infer; +export type WorkItemFilterOptionsResponse = z.infer; + const sessionsSchema = z.record(z.string().min(1).max(64), sessionSchema); const metadataSchema = z .union([z.record(z.string(), z.unknown()), z.null()]) @@ -1000,6 +1136,14 @@ export const FACTORY_ROUTE_CONTRACTS = { pathSchema: boardPathSchema, responseSchema: storedBoardResponseSchema, }, + boardPhases: { + method: 'GET', + path: '/web/factory/projects/:id/boards/:boardKey/phases', + description: 'List the cards under each phase of a board view, in order, with how many match', + pathSchema: boardPathSchema, + querySchema: boardPhasesQuerySchema, + responseSchema: boardPhasesResponseSchema, + }, boardCreate: { method: 'POST', path: '/web/factory/projects/:id/boards', @@ -1115,6 +1259,13 @@ export const FACTORY_ROUTE_CONTRACTS = { querySchema: workItemActivityQuerySchema, responseSchema: workItemActivityResponseSchema, }, + workItemFilterOptions: { + method: 'GET', + path: '/web/factory/projects/:id/work-items/filter-options', + description: 'List the labels and people the cards of a project can be filtered by', + pathSchema: projectPathSchema, + responseSchema: workItemFilterOptionsResponseSchema, + }, workItemCreate: { method: 'POST', path: '/web/factory/projects/:id/work-items', diff --git a/mastracode/factory/src/routes/work-item-selection.ts b/mastracode/factory/src/routes/work-item-selection.ts index 0d00bb3bb3f..0a915c06754 100644 --- a/mastracode/factory/src/routes/work-item-selection.ts +++ b/mastracode/factory/src/routes/work-item-selection.ts @@ -1,15 +1,6 @@ import type { Card } from '../storage/domains/work-items/base.js'; -import { workItemNumber } from '../tools/read-tools.js'; - -/** The words of a typed search, lowercased. */ -export function searchWords(query: string): string[] { - return query.toLowerCase().split(/\s+/).filter(Boolean); -} - -/** Whether every word is somewhere in `text`, which the caller has lowercased. */ -export function hasEveryWord(text: string, words: readonly string[]): boolean { - return words.every(word => text.includes(word)); -} +import { cardSearchText } from '../work-items/card-search-text.js'; +import { hasEveryWord, searchWords } from '../work-items/search-words.js'; interface UnstartedCard { card: Card; @@ -20,15 +11,6 @@ interface UnstartedCard { // One list per board version: `listShared` returns the same array until a card changes. const unstartedByBoard = new WeakMap(); -/** What a search reads of a card: its title, its key (`ENG-42`), its number and its source id. */ -function searchText(card: Card): string { - const number = workItemNumber(card); - // `#12` also answers a search for `12`. - return [card.title, card.workItem.key, number === null ? null : `#${number}`, card.externalSource?.externalId] - .join(' ') - .toLowerCase(); -} - function unstarted(board: readonly Card[]): UnstartedCard[] { let cards = unstartedByBoard.get(board); if (!cards) { @@ -36,7 +18,7 @@ function unstarted(board: readonly Card[]): UnstartedCard[] { .filter(card => Object.keys(card.sessions).length === 0) // Cards updated at the same instant keep the board's order, newest created first. .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime()) - .map(card => ({ card, text: searchText(card) })); + .map(card => ({ card, text: cardSearchText(card) })); unstartedByBoard.set(board, cards); } return cards; diff --git a/mastracode/factory/src/routes/work-item-starters.ts b/mastracode/factory/src/routes/work-item-starters.ts index 6801d87055b..66dc7ba3418 100644 --- a/mastracode/factory/src/routes/work-item-starters.ts +++ b/mastracode/factory/src/routes/work-item-starters.ts @@ -11,6 +11,8 @@ import { boardFlow, boardForWorkItem, isPullRequestCard } from '../boards/index. import type { FactoryRuleBoardFlow } from '../rules/types.js'; import type { Card, FactoryDeferredDecisionRecord } from '../storage/domains/work-items/base.js'; import { workItemBranchSource } from '../work-item-branch.js'; +import { sourceMetadata } from '../work-items/card-facts.js'; +import { metadataLabels } from '../work-items/card-labels.js'; import type { workItemStartersResponseSchema } from './contracts.js'; export type WorkItemStarters = z.infer; @@ -54,20 +56,6 @@ export function cardsWithFailedRun( return failed; } -/** - * What the card's source says about it. A Factory card has no source: its facts are its work - * item's with the card's own on top, as clients read them. A synced one keeps them on its work item. - */ -function sourceFacts(card: Card): Record { - const { workItem } = card; - if (workItem.provider === 'factory') return { ...workItem.metadata, ...card.metadata }; - return { ...workItem.metadata, labels: workItem.labels, state: workItem.state }; -} - -function labelsOf({ labels }: Record): string[] { - return Array.isArray(labels) ? labels.filter((label): label is string => typeof label === 'string') : []; -} - function isPullRequest(card: Card): boolean { return isPullRequestCard({ source: workItemBranchSource(card.externalSource) }); } @@ -185,7 +173,7 @@ export function workItemStarters({ (board.initialPhase === firstPhase && !card.stages.some(stage => Object.hasOwn(board.phases, stage))); if (isPullRequest(card)) { - const facts = sourceFacts(card); + const facts = sourceMetadata(card); if (!isOpenPullRequest(facts, finished)) continue; // Factory's verdict sits on the card, over what the source reports. const verdict = { ...card.workItem.metadata, ...card.metadata }; @@ -214,7 +202,7 @@ export function workItemStarters({ const notStarted = resting || (triagePhase !== undefined && card.stages.includes(triagePhase)); if (!notStarted) continue; - const labels = labelsOf(sourceFacts(card)); + const labels = metadataLabels(sourceMetadata(card)); if ( seats.planner !== undefined && labels.some(label => label.toLowerCase() === 'bug') && diff --git a/mastracode/factory/src/routes/work-items.test.ts b/mastracode/factory/src/routes/work-items.test.ts index 5433754e38d..8aa11b92e64 100644 --- a/mastracode/factory/src/routes/work-items.test.ts +++ b/mastracode/factory/src/routes/work-items.test.ts @@ -65,6 +65,7 @@ import { createFactoryStorageForTests } from '../storage/test-utils.js'; import type { FactoryStorageTestSeed } from '../storage/test-utils.js'; import { boardCheck } from '../work-items/board-check.js'; import { FACTORY_ROUTE_CONTRACTS } from './contracts.js'; +import type { BoardPhasesResponse } from './contracts.js'; import { fakeRouteAuth, mountApiRoutes } from './test-utils.js'; import { parseCreateWorkItem, parseUpdateWorkItem, WorkItemRoutes } from './work-items.js'; @@ -3073,6 +3074,629 @@ describe('GET /web/factory/projects/:id/work-items/activity', () => { }); }); +describe('GET /web/factory/projects/:id/boards/:boardKey/phases', () => { + type Phases = BoardPhasesResponse; + interface Filed { + id: string; + revision: number; + } + + const teammate = { workosId: 'u2', organizationId: 'org1' }; + const itemsPath = () => `/web/factory/projects/${PROJECT_ID}/work-items`; + const phasesPath = (query = '', board = 'work') => + `/web/factory/projects/${PROJECT_ID}/boards/${board}/phases${query && `?${query}`}`; + const at = (instant: string) => vi.setSystemTime(new Date(instant)); + + const file = async (externalId: string, overrides: Record = {}, user = orgUser): Promise => { + const res = await json( + 'POST', + itemsPath(), + createBody({ + externalSource: { integrationId: 'github', type: 'issue', externalId }, + title: `Card ${externalId}`, + metadata: {}, + ...overrides, + }), + user, + ); + expect(res.ok).toBe(true); + return (await res.json()).workItem; + }; + + const move = async (card: Filed, stage: string, user = orgUser) => { + const res = await json( + 'POST', + `${itemsPath()}/${card.id}/transition`, + { board: 'work', stage, expectedRevision: card.revision, requestId: crypto.randomUUID(), cause: 'board_drag' }, + user, + ); + expect(res.status).toBe(200); + }; + + const read = async (query = '', app = buildApp(orgUser)): Promise => { + const res = await app.request(phasesPath(query)); + expect(res.status).toBe(200); + return FACTORY_ROUTE_CONTRACTS.boardPhases.responseSchema.parse(await res.json()); + }; + + const under = (body: Phases, phase: string) => { + const found = body.phases.find(entry => entry.phase === phase); + if (!found) throw new Error(`The answer has no ${phase} phase`); + return { total: found.total, ids: found.cards.map(card => card.id) }; + }; + + beforeEach(() => void vi.useFakeTimers({ toFake: ['Date'], now: new Date('2026-11-01T10:00:00Z') })); + + it('401s without a user and 404s for projects outside the org', async () => { + expect((await json('GET', phasesPath(), undefined, null)).status).toBe(401); + + await seedProject('other-org'); + expect((await json('GET', phasesPath())).status).toBe(404); + }); + + it('lists the board’s phases in order, each with how many cards it holds and the first of them, latest entry first', async () => { + await file('1'); + at('2026-11-01T10:01:00Z'); + const second = await file('2'); + at('2026-11-01T10:02:00Z'); + const third = await file('3'); + const { boards } = await (await json('GET', `/web/factory/projects/${PROJECT_ID}/boards`)).json(); + const phases: string[] = boards + .find((board: { id: string }) => board.id === 'work') + .phases.map((phase: { id: string }) => phase.id); + + const body = await read('limit=2'); + + expect(body.phases.map(entry => entry.phase)).toEqual(phases); + expect(under(body, 'intake')).toEqual({ total: 3, ids: [third.id, second.id] }); + expect(body.phases.filter(entry => entry.phase !== 'intake').map(entry => entry.total)).toEqual( + phases.slice(1).map(() => 0), + ); + expect(body).toMatchObject({ boardTotal: 3, matchingTotal: 3, related: [] }); + }); + + it('shows a card that is in none of the board’s phases under the first one, and no card of another board', async () => { + const release = defineBoard({ + id: 'release', + title: 'Release', + initialPhase: 'queued', + phases: { + queued: { title: 'Queued', kind: 'resting', next: 'shipped' }, + shipped: { title: 'Shipped', kind: 'terminal' }, + }, + transitionPolicy: () => undefined, + }); + const app = buildApp(orgUser, undefined, undefined, new Set(), createBoardRegistry({ boards: [release] })); + const filed = await app.request(itemsPath(), { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify(createBody({ externalSource: null, board: 'release', stages: ['queued'], metadata: {} })), + }); + expect(filed.ok).toBe(true); + const onRelease: Filed = (await filed.json()).workItem; + const lost = await file('1'); + await seed.workItems.update({ orgId: 'org1', id: lost.id, userId: 'u1', patch: { stages: ['retired-lane'] } }); + + const work = await read('', app); + const other = FACTORY_ROUTE_CONTRACTS.boardPhases.responseSchema.parse( + await (await app.request(phasesPath('', 'release'))).json(), + ); + + expect(work.phases[0]?.cards.map(card => card.id)).toEqual([lost.id]); + expect(work.phases.slice(1).every(entry => entry.total === 0)).toBe(true); + expect(work.boardTotal).toBe(1); + expect(other.phases.map(entry => [entry.phase, entry.cards.map(card => card.id)])).toEqual([ + ['queued', [onRelease.id]], + ['shipped', []], + ]); + }); + + it('lists a card that is in two phases under both, and counts it once among the board’s cards', async () => { + const both = await file('1', { metadata: { labels: ['bug'] } }); + await seed.workItems.update({ + orgId: 'org1', + id: both.id, + userId: 'u1', + patch: { stages: ['triage', 'execute'] }, + }); + await file('2'); + + const whole = await read(); + const bugs = await read('label=bug'); + + expect(under(whole, 'triage').ids).toEqual([both.id]); + expect(under(whole, 'execute').ids).toEqual([both.id]); + expect(whole).toMatchObject({ boardTotal: 2, matchingTotal: 2 }); + expect([under(bugs, 'triage').total, under(bugs, 'execute').total, under(bugs, 'intake').total]).toEqual([1, 1, 0]); + // The filters lower how many match; the board still has both cards. + expect(bugs).toMatchObject({ boardTotal: 2, matchingTotal: 1 }); + }); + + describe('the order of a phase (?sort=)', () => { + it('orders by creation when asked, newest or oldest first, whatever entered the phase last', async () => { + const older = await file('1'); + at('2026-11-01T10:01:00Z'); + const newer = await file('2'); + at('2026-11-01T10:02:00Z'); + await move(newer, 'planning'); + at('2026-11-01T10:03:00Z'); + await move(older, 'planning'); + + expect(under(await read(), 'planning').ids).toEqual([older.id, newer.id]); + expect(under(await read('sort=created-newest'), 'planning').ids).toEqual([newer.id, older.id]); + expect(under(await read('sort=created-oldest'), 'planning').ids).toEqual([older.id, newer.id]); + }); + + it('puts first the cards the signed-in user last moved into the phase', async () => { + const [a, b, c] = [await file('1'), await file('2'), await file('3')]; + at('2026-11-01T10:01:00Z'); + await move(a, 'planning'); + at('2026-11-01T10:02:00Z'); + await move(b, 'planning', teammate); + at('2026-11-01T10:03:00Z'); + await move(c, 'planning'); + + expect(under(await read('sort=recent'), 'planning').ids).toEqual([c.id, b.id, a.id]); + expect(under(await read('sort=recent-mine'), 'planning').ids).toEqual([c.id, a.id, b.id]); + expect(under(await read('sort=recent-mine', buildApp(teammate)), 'planning').ids).toEqual([b.id, c.id, a.id]); + }); + + it('keeps cards that entered at the same instant in one order: by id, descending', async () => { + const cards = [await file('1'), await file('2'), await file('3')]; + + expect(under(await read(), 'intake').ids).toEqual( + cards + .map(card => card.id) + .sort() + .reverse(), + ); + }); + }); + + describe('how deep a phase is listed (?limit=, ?window=, ?item=)', () => { + const fileTwoPhases = async () => { + const intake: Filed[] = []; + const planning: Filed[] = []; + for (const [nth, stage] of ['intake', 'intake', 'intake', 'planning', 'planning'].entries()) { + at(`2026-11-01T10:0${nth}:00Z`); + const card = await file(String(nth)); + if (stage === 'planning') await move(card, 'planning'); + (stage === 'planning' ? planning : intake).push(card); + } + // Latest entry first, as the phases list them. + return { intake: intake.reverse().map(card => card.id), planning: planning.reverse().map(card => card.id) }; + }; + + it('deepens only the phase a window names', async () => { + const { intake, planning } = await fileTwoPhases(); + + const body = await read('limit=1&window=intake:2'); + + expect(under(body, 'intake')).toEqual({ total: 3, ids: intake.slice(0, 2) }); + expect(under(body, 'planning')).toEqual({ total: 2, ids: planning.slice(0, 1) }); + }); + + it('answers for the asked card with its place and its body, and lists its phase no deeper', async () => { + const { intake, planning } = await fileTwoPhases(); + + const body = await read(`limit=1&item=${intake[2]}&cards=true`); + + expect(under(body, 'intake')).toEqual({ total: 3, ids: intake.slice(0, 1) }); + expect(under(body, 'planning')).toEqual({ total: 2, ids: planning.slice(0, 1) }); + expect(body.item).toEqual({ + id: intake[2], + version: expect.any(String), + places: [{ phase: 'intake', position: 2 }], + }); + // The first card of each phase, then the asked one: three bodies, not the phase above it. + expect(body.workItems?.map(card => card.id)).toEqual([intake[0], planning[0], intake[2]]); + expect(body.workItems?.[2]?.version).toBe(body.item?.version); + }); + + it('answers no asked card for one the board does not hold', async () => { + await fileTwoPhases(); + + const body = await read(`limit=1&item=${crypto.randomUUID()}`); + + expect(body).not.toHaveProperty('item'); + }); + + it('ignores a window for a phase the board no longer has, so a reader that deepened it keeps its board', async () => { + const { intake, planning } = await fileTwoPhases(); + + const body = await read('limit=1&window=retired-phase:5&window=planning:2'); + + expect(under(body, 'intake')).toEqual({ total: 3, ids: intake.slice(0, 1) }); + expect(under(body, 'planning')).toEqual({ total: 2, ids: planning }); + }); + }); + + it.each([ + ['an order it does not know', 'sort=sideways'], + ['a window without a count', 'window=intake'], + ['a window of no card', 'window=intake:0'], + ['two windows for one phase', 'window=intake:2&window=intake:3'], + ['an asked card that is not an id', 'item=first'], + ['a card bodies flag other than true', 'cards=yes'], + ])('refuses %s rather than answering another view', async (_case, query) => { + const res = await json('GET', phasesPath(query)); + + expect(res.status).toBe(400); + expect(await res.json()).toEqual({ error: 'invalid_phases_query' }); + }); + + it('404s for a board the project does not have', async () => { + const res = await json('GET', phasesPath('', 'missing')); + + expect(res.status).toBe(404); + expect(await res.json()).toEqual({ error: 'board_not_found' }); + }); + + describe('a searched or filtered view', () => { + const fileMixedBoard = async () => { + const issue = await file('1', { + title: 'Fix the login flow', + metadata: { number: 101, labels: ['bug', 'Memory'], author: 'octocat', assignees: ['hubot'] }, + }); + const pullRequest = await file('pr-7', { + externalSource: { integrationId: 'github', type: 'pull-request', externalId: 'pr-7' }, + title: 'Tidy the palette', + metadata: { number: 7, labels: ['bug'], author: 'monalisa', requestedReviewers: ['defunkt'] }, + }); + const linearA = await file('LIN-1', { + externalSource: { integrationId: 'linear', type: 'issue', externalId: 'LIN-1' }, + title: 'Palette contrast', + metadata: { linearProjectId: 'project-a', assignee: 'Ada' }, + }); + const linearB = await file('LIN-2', { + externalSource: { integrationId: 'linear', type: 'issue', externalId: 'LIN-2' }, + title: 'Slow sync', + metadata: { linearProjectId: 'project-b' }, + }); + const byHand = await file('', { externalSource: null, title: 'Write the changelog' }, teammate); + return new Map([ + [issue.id, 'issue'], + [pullRequest.id, 'pull request'], + [linearA.id, 'linear a'], + [linearB.id, 'linear b'], + [byHand.id, 'by hand'], + ]); + }; + + it.each([ + ['a search word', 'q=palette', ['linear a', 'pull request']], + ['every search word', 'q=the%20login', ['issue']], + ['a card number', 'q=%23101', ['issue']], + ['a label', 'label=bug', ['issue', 'pull request']], + ['every picked label', 'label=bug&label=Memory', ['issue']], + ['a source', 'source=github', ['issue', 'pull request']], + ['cards filed by hand', 'source=manual', ['by hand']], + ['pull requests', 'source=pull-request', ['pull request']], + ['any picked source', 'source=pull-request&source=linear', ['linear a', 'linear b', 'pull request']], + ['a Linear project picked alone', 'linearProject=project-a', ['linear a']], + ['a source’s author', 'author=github:octocat', ['issue']], + ['the person who filed a card by hand', 'author=factory:u2', ['by hand']], + ['an assignee', 'assignee=github:hubot&assignee=linear:ada', ['issue', 'linear a']], + ['a requested reviewer', 'reviewer=github:defunkt', ['pull request']], + ['a person who worked on the card', 'worked=factory:u2', ['by hand']], + ['a person involved in any way', 'teammate=github:defunkt&teammate=github:hubot', ['issue', 'pull request']], + ['every field at once', 'label=bug&source=github&author=github:monalisa', ['pull request']], + ['a search and a filter at once', 'label=bug&q=login', ['issue']], + ['nothing, when no card matches every field', 'label=Memory&reviewer=github:defunkt', []], + ])('keeps the cards that match %s, and counts only them', async (_case, query, expected) => { + const names = await fileMixedBoard(); + + const body = await read(query); + + const intake = under(body, 'intake'); + expect(intake.ids.map(id => names.get(id)).sort()).toEqual(expected); + expect(intake.total).toBe(expected.length); + expect(body.matchingTotal).toBe(expected.length); + // The board's own count ignores the search and the filters. + expect(body.boardTotal).toBe(5); + }); + }); + + describe('the cards an answer names', () => { + const fileParentAndPullRequest = async () => { + const parent = await file('parent'); + at('2026-11-01T10:01:00Z'); + const pullRequest = await file('child', { + externalSource: { integrationId: 'github', type: 'pull-request', externalId: 'child' }, + parentWorkItemId: parent.id, + }); + return { parent, pullRequest }; + }; + + it('names the cards related to a listed card that no phase lists, without any card body', async () => { + const { parent, pullRequest } = await fileParentAndPullRequest(); + + const res = await json('GET', phasesPath('limit=1')); + const raw = await res.json(); + const body = FACTORY_ROUTE_CONTRACTS.boardPhases.responseSchema.parse(raw); + + expect(under(body, 'intake')).toEqual({ total: 2, ids: [pullRequest.id] }); + expect(body.related.map(card => card.id)).toEqual([parent.id]); + expect(raw).not.toHaveProperty('workItems'); + // Once a phase lists the parent, it is no longer only related. + expect((await read()).related).toEqual([]); + }); + + it('sends with cards=true the body of every named card, as the list route sends it', async () => { + const { parent, pullRequest } = await fileParentAndPullRequest(); + await move(await file('unrelated'), 'planning'); + const listed = await (await json('GET', itemsPath())).json(); + const wire = (id: string) => listed.workItems.find((card: { id: string }) => card.id === id); + + const raw = await (await json('GET', phasesPath('limit=1&window=planning:1&cards=true'))).json(); + + const unrelated = raw.phases.find((entry: { phase: string }) => entry.phase === 'planning').cards[0]; + const sent = raw.workItems.map(({ version: _version, ...card }: { version: string }) => card); + expect(sent).toEqual([wire(pullRequest.id), wire(unrelated.id), wire(parent.id)]); + // A reader tells its copy of a card from the answer's by its version. + expect(raw.related).toEqual([{ id: parent.id, version: raw.workItems[2].version }]); + expect(raw.workItems[2].version).toEqual(expect.any(String)); + }); + + it('declares the version of each body it sends, so a typed reader takes it from the answer', async () => { + await file('1'); + const schema = FACTORY_ROUTE_CONTRACTS.boardPhases.responseSchema; + + const raw = await (await json('GET', phasesPath('cards=true'))).json(); + + expect(schema.parse(raw)).toEqual(raw); + const [{ version: _version, ...unversioned }] = raw.workItems; + expect(schema.safeParse({ ...raw, workItems: [unversioned] }).success).toBe(false); + }); + + it('names a card by the same version in the by-id read, so a reader can tell it holds the body', async () => { + const card = await file('1'); + + const phases = await read(); + const byId = await (await json('GET', `${itemsPath()}?workItemId=${card.id}`)).json(); + + expect(byId.workItems).toMatchObject([{ id: card.id, version: phases.phases[0]?.cards[0]?.version }]); + }); + + it('reports which sessions of the named cards run or wait, and none of an unlisted card', async () => { + const start = async (sessionId: string) => { + await seed.workItems.prepareRunStart({ + orgId: 'org1', + userId: 'u1', + factoryProjectId: PROJECT_ID, + workItem: { input: { title: `Work for ${sessionId}`, stages: ['execute'] } }, + role: 'execute', + session: { sessionId, branch: `factory/${sessionId}`, threadId: `thread-${sessionId}` }, + resourceId: sessionId, + kickoffKey: `kickoff-${sessionId}`, + kickoffMessage: null, + }); + }; + await start('session-older'); + at('2026-11-01T10:01:00Z'); + await start('session-newer'); + const sessions = new Set(['session-older', 'session-newer']); + const app = buildApp(orgUser, undefined, undefined, sessions, undefined, new Set(['session-newer'])); + + const firstOnly = await read('limit=1', app); + const both = await read('', app); + + expect(firstOnly).toMatchObject({ runningSessionIds: ['session-newer'], parkedSessionIds: ['session-newer'] }); + expect(both.runningSessionIds.toSorted()).toEqual(['session-newer', 'session-older']); + expect(both.parkedSessionIds).toEqual(['session-newer']); + }); + }); + + describe('asked again by a board that kept the answer', () => { + it('answers 304 without a body while nothing the view shows changed', async () => { + await file('1'); + const app = buildApp(orgUser); + + const first = await app.request(phasesPath()); + const etag = first.headers.get('etag'); + expect(first.status).toBe(200); + expect(etag).toBeTruthy(); + expect(first.headers.get('cache-control')).toBe('private, no-cache'); + + const again = await app.request(phasesPath(), { headers: { 'if-none-match': etag! } }); + expect(again.status).toBe(304); + expect(await again.text()).toBe(''); + }); + + it('sends the answer again, with the card’s new version, once a listed card changes', async () => { + const card = await file('1'); + const app = buildApp(orgUser); + const first = await app.request(phasesPath()); + const etag = first.headers.get('etag'); + const before = FACTORY_ROUTE_CONTRACTS.boardPhases.responseSchema.parse(await first.json()); + + at('2026-11-01T10:05:00Z'); + await json('PATCH', `/web/factory/work-items/${card.id}`, { title: 'Renamed' }); + + const after = await app.request(phasesPath(), { headers: { 'if-none-match': etag! } }); + expect(after.status).toBe(200); + const body = FACTORY_ROUTE_CONTRACTS.boardPhases.responseSchema.parse(await after.json()); + expect(under(body, 'intake').ids).toEqual([card.id]); + expect(body.phases[0]?.cards[0]?.version).not.toBe(before.phases[0]?.cards[0]?.version); + }); + + it('sends a new version when a source sync changes a listed card in the millisecond of its last write', async () => { + const card = await file('1'); + at('2026-11-01T10:00:07Z'); + await json('PATCH', `/web/factory/work-items/${card.id}`, { title: 'Renamed' }); + const app = buildApp(orgUser); + const view = phasesPath('cards=true'); + const first = await app.request(view); + const before = await first.json(); + + // The clock has not moved: the sync stamps the card with the instant the rename did. + await seed.workItems.syncWorkItemSource({ + orgId: 'org1', + factoryProjectId: PROJECT_ID, + provider: 'github', + externalId: before.workItems[0].workItem.externalId, + patch: { labels: ['urgent'] }, + }); + + const after = await app.request(view, { headers: { 'if-none-match': first.headers.get('etag')! } }); + expect(after.status).toBe(200); + const body = await after.json(); + expect(body.workItems[0]).toMatchObject({ changedAt: before.workItems[0].changedAt }); + expect(body.workItems[0].workItem.labels).toEqual(['urgent']); + expect(body.phases[0].cards[0].version).not.toBe(before.phases[0].cards[0].version); + expect(body.workItems[0].version).toBe(body.phases[0].cards[0].version); + }); + + it('sends a new version of a Review card that reads as a Work card once Review closes, though nothing wrote it', async () => { + const closed = await file('closed', { + externalSource: { integrationId: 'github', type: 'pull-request', externalId: 'closed' }, + }); + const open = await file('open', { + externalSource: { integrationId: 'github', type: 'pull-request', externalId: 'open' }, + }); + // Rows as the retired Review board left them: one done, one still in review. + const stored = (id: string, stages: string[]) => + seed.storage.ops.updateMany('factory_board_items', { id }, { board: 'review', stages }); + await stored(closed.id, ['done']); + await stored(open.id, ['review']); + const app = buildApp(orgUser); + const byId = async () => + (await (await app.request(`${itemsPath()}?workItemId=${closed.id}`)).json()).workItems[0]; + at('2026-11-01T10:01:00Z'); + await json('PATCH', `/web/factory/work-items/${open.id}`, { title: 'Still open' }); + const held = await byId(); + expect(held).toMatchObject({ board: 'review' }); + const etag = (await app.request(phasesPath())).headers.get('etag'); + + at('2026-11-01T10:02:00Z'); + await seed.workItems.update({ + orgId: 'org1', + id: open.id, + userId: orgUser.workosId, + patch: { stages: ['done'] }, + }); + + const after = await app.request(phasesPath(), { headers: { 'if-none-match': etag! } }); + expect(after.status).toBe(200); + const done = FACTORY_ROUTE_CONTRACTS.boardPhases.responseSchema + .parse(await after.json()) + .phases.find(entry => entry.phase === 'done'); + const named = done?.cards.find(card => card.id === closed.id); + const now = await byId(); + expect(now).toMatchObject({ board: 'work', changedAt: held.changedAt }); + expect(named?.version).toBe(now.version); + expect(named?.version).not.toBe(held.version); + }); + + it('still answers 304 when the card that changed is outside every window', async () => { + const deep = await file('1'); + at('2026-11-01T10:01:00Z'); + await file('2'); + const app = buildApp(orgUser); + const etag = (await app.request(phasesPath('limit=1'))).headers.get('etag'); + + at('2026-11-01T10:05:00Z'); + await json('PATCH', `/web/factory/work-items/${deep.id}`, { title: 'Renamed below the fold' }); + + const again = await app.request(phasesPath('limit=1'), { headers: { 'if-none-match': etag! } }); + expect(again.status).toBe(304); + }); + + it('sends the answer again once a total changes, though the listed cards did not', async () => { + const oldest = await file('1'); + const app = buildApp(orgUser); + const view = phasesPath('limit=1&sort=created-oldest'); + const etag = (await app.request(view)).headers.get('etag'); + + at('2026-11-01T10:05:00Z'); + await file('2'); + + const after = await app.request(view, { headers: { 'if-none-match': etag! } }); + expect(after.status).toBe(200); + const body = FACTORY_ROUTE_CONTRACTS.boardPhases.responseSchema.parse(await after.json()); + expect(under(body, 'intake')).toEqual({ total: 2, ids: [oldest.id] }); + }); + + it('gzips the answer for a reader that accepts it', async () => { + const card = await file('1'); + + const res = await buildApp(orgUser).request(phasesPath(), { headers: { 'accept-encoding': 'gzip' } }); + + expect(res.headers.get('content-encoding')).toBe('gzip'); + const body = JSON.parse(gunzipSync(Buffer.from(await res.arrayBuffer())).toString()); + expect(under(body, 'intake').ids).toEqual([card.id]); + }); + }); +}); + +describe('GET /web/factory/projects/:id/work-items/filter-options', () => { + const itemsPath = () => `/web/factory/projects/${PROJECT_ID}/work-items`; + const optionsPath = () => `${itemsPath()}/filter-options`; + const file = (overrides: Record, user = orgUser) => + json('POST', itemsPath(), createBody({ metadata: {}, ...overrides }), user); + + it('401s without a user and 404s for projects outside the org', async () => { + expect((await json('GET', optionsPath(), undefined, null)).status).toBe(401); + + await seedProject('other-org'); + expect((await json('GET', optionsPath())).status).toBe(404); + }); + + it('offers every label, every person a source names and every Factory user who acted, over all the project’s cards', async () => { + await file({ + externalSource: { integrationId: 'github', type: 'issue', externalId: '1' }, + metadata: { labels: ['bug', 'Memory'], author: 'octocat', assignees: ['hubot'] }, + }); + await file({ + externalSource: { integrationId: 'github', type: 'pull-request', externalId: 'pr-7' }, + metadata: { labels: ['bug', 'area: docs'], author: 'octocat', requestedReviewers: ['defunkt'] }, + }); + await file({ + externalSource: { integrationId: 'linear', type: 'issue', externalId: 'LIN-1' }, + metadata: { assignee: 'Ada' }, + }); + await file({ externalSource: null, title: 'Filed by hand' }, { workosId: 'u2', organizationId: 'org1' }); + + const res = await json('GET', optionsPath()); + + expect(res.status).toBe(200); + const body = await res.json(); + expect(FACTORY_ROUTE_CONTRACTS.workItemFilterOptions.responseSchema.parse(body)).toEqual(body); + expect(body).toEqual({ + labels: ['area: docs', 'bug', 'Memory'], + people: [ + { id: 'linear:ada', name: 'Ada', source: 'linear' }, + { id: 'github:defunkt', name: 'defunkt', source: 'github' }, + { id: 'github:hubot', name: 'hubot', source: 'github' }, + { id: 'github:octocat', name: 'octocat', source: 'github' }, + ], + actorIds: ['u1', 'u2'], + }); + }); + + it('answers 304 while no card changed, and the options again once one did', async () => { + await file({ metadata: { labels: ['bug'] } }); + const app = buildApp(orgUser); + const first = await app.request(optionsPath()); + const etag = first.headers.get('etag'); + expect(first.status).toBe(200); + expect(first.headers.get('cache-control')).toBe('private, no-cache'); + + const again = await app.request(optionsPath(), { headers: { 'if-none-match': etag! } }); + expect(again.status).toBe(304); + expect(await again.text()).toBe(''); + + await file({ + externalSource: { integrationId: 'github', type: 'issue', externalId: '2' }, + metadata: { labels: ['docs'] }, + }); + + const after = await app.request(optionsPath(), { headers: { 'if-none-match': etag! } }); + expect(after.status).toBe(200); + expect((await after.json()).labels).toEqual(['bug', 'docs']); + }); +}); + describe('GET /web/factory/projects/:id/health/thresholds', () => { it('401s without a user and 404s for projects outside the org', async () => { expect((await json('GET', `/web/factory/projects/${PROJECT_ID}/health/thresholds`, undefined, null)).status).toBe( diff --git a/mastracode/factory/src/routes/work-items.ts b/mastracode/factory/src/routes/work-items.ts index 5ec0ae27174..a8d9dec163f 100644 --- a/mastracode/factory/src/routes/work-items.ts +++ b/mastracode/factory/src/routes/work-items.ts @@ -11,7 +11,7 @@ import type { ApiRoute } from '@mastra/core/server'; import { registerApiRoute } from '@mastra/core/server'; import type { Context } from 'hono'; -import { boardFlow, boardPhaseOutcomes, DEFAULT_BOARD_ID, isPullRequestCard } from '../boards/index.js'; +import { boardFlow, boardPhaseOutcomes, DEFAULT_BOARD_ID } from '../boards/index.js'; import type { BoardRegistry } from '../boards/index.js'; import type { IntakeRoutesReader } from '../boards/intake-routing.js'; import { toBoardSource } from '../boards/project-boards.js'; @@ -47,13 +47,22 @@ import { WorkItemUpdateConflictError, } from '../storage/domains/work-items/base.js'; import { computeFactoryMetrics, parseMetricsRange } from '../storage/domains/work-items/metrics.js'; -import { workItemBranchSource } from '../work-item-branch.js'; +import { workItemFilterOptions } from '../work-items/board-filter-options.js'; +import { boardPhases } from '../work-items/board-phases.js'; import { createFactoryWorkItem } from '../work-items/create-work-item.js'; import { resolveFactoryProposal, retryFactoryDecision } from '../work-items/decision-actions.js'; -import { relatedCardIndex } from '../work-items/related-cards.js'; -import type { PullRequestFacts } from '../work-items/related-cards.js'; +import { relatedCardsIn } from '../work-items/list-related-cards.js'; import { buildAttentionRoutes, factoryDecisionType } from './attention.js'; -import { boardSnapshot, hashedBody, listCheck, matchesEtag, movedBody, scopedSnapshot } from './board-snapshot.js'; +import { + boardSnapshot, + hashedBody, + listCheck, + matchesEtag, + movedBody, + namedBody, + scopedSnapshot, + sha1, +} from './board-snapshot.js'; import type { BoardSnapshot } from './board-snapshot.js'; import { FACTORY_ROUTE_CONTRACTS } from './contracts.js'; import type { RouteDependencies } from './route.js'; @@ -98,6 +107,24 @@ function toWireWorkItem(item: Card): Card { }; } +// One hash per card object: `listShared` keeps a card's object until the card changes. +const wireVersions = new WeakMap(); + +/** + * Names the body a card is sent with. It is a hash of that body, not a stamp: two bodies of one + * card can carry the same `changedAt`, and a card can read differently without a write. + */ +function wireVersion(card: Card): string { + let version = wireVersions.get(card); + if (version === undefined) wireVersions.set(card, (version = sha1(JSON.stringify(toWireWorkItem(card))))); + return version; +} + +/** The card for a reader that keeps it between reads, and tells by `version` whether it holds this body. */ +function toVersionedWireWorkItem(card: Card): Card & { version: string } { + return { ...toWireWorkItem(card), version: wireVersion(card) }; +} + /** Session ids of the listed cards that the predicate picks, each once. */ function sessionIdsWhere(items: readonly Card[], predicate: (sessionId: string) => boolean): string[] { const picked = new Set(); @@ -109,26 +136,34 @@ function sessionIdsWhere(items: readonly Card[], predicate: (sessionId: string) return [...picked]; } -const CARD_PULL_REQUESTS: PullRequestFacts = { - isPullRequest: card => isPullRequestCard({ source: workItemBranchSource(card.externalSource) }), - headBranch: card => { - const branch = card.workItem.metadata?.headBranch; - return typeof branch === 'string' ? branch : undefined; - }, -}; +/** Sends a JSON body, gzipped for a reader that accepts it. */ +async function sendJson( + c: Context, + body: Pick, + headers: Record, +): Promise { + headers['Content-Type'] = 'application/json; charset=UTF-8'; + headers.Vary = 'Accept-Encoding'; + if (!/\bgzip\b/.test(c.req.header('accept-encoding') ?? '')) return c.body(body.json, 200, headers); + headers['Content-Encoding'] = 'gzip'; + return c.body(new Uint8Array(await body.gzipped()), 200, headers); +} + +/** Sends an answer its reader revalidates: a 304 without a body when the reader holds it already. */ +async function sendRevalidated(c: Context, answer: BoardSnapshot): Promise { + const headers = { ETag: answer.etag, 'Cache-Control': 'private, no-cache' }; + if (matchesEtag(c.req.header('if-none-match'), answer.etag)) { + return c.body(null, 304, { ...headers, Vary: 'Accept-Encoding' }); + } + return sendJson(c, answer, headers); +} -// One index per board version: `listShared` returns the same array until a card changes. -const relatedCards = new WeakMap Card[]>(); // One list per board version, so every tab's sidebar shares its serialization. const cardsInSessions = new WeakMap(); /** The cards `holds` picks, and the cards related to them, in board order. */ function withRelatedCards(board: readonly Card[], holds: (card: Card) => boolean): Card[] { - let relatedTo = relatedCards.get(board); - if (!relatedTo) { - relatedTo = relatedCardIndex(board, CARD_PULL_REQUESTS); - relatedCards.set(board, relatedTo); - } + const relatedTo = relatedCardsIn(board); const picked = new Set(); for (const card of board) { if (!holds(card)) continue; @@ -499,30 +534,20 @@ export class WorkItemRoutes extends Route { const items = part ?? board; const running = sessionIdsWhere(items, sessionId => liveSessions.isRunning(sessionId)); const parked = sessionIdsWhere(items, sessionId => liveSessions.parked(sessionId) !== undefined); - const send = async (body: Pick, headers: Record) => { - headers['Content-Type'] = 'application/json; charset=UTF-8'; - headers.Vary = 'Accept-Encoding'; - if (!/\bgzip\b/.test(c.req.header('accept-encoding') ?? '')) return c.body(body.json, 200, headers); - headers['Content-Encoding'] = 'gzip'; - return c.body(new Uint8Array(await body.gzipped()), 200, headers); - }; // A tab that kept the board gets what moved since its cursor: a body the size of the change. if (list.changed) { const workItems = list.changed.map(toWireWorkItem); const moved = { workItems, removedIds: list.removed, check: listCheck(board), cursor: list.cursor }; - return send(movedBody({ ...moved, runningSessionIds: running, parkedSessionIds: parked }), { + return sendJson(context, movedBody({ ...moved, runningSessionIds: running, parkedSessionIds: parked }), { 'Cache-Control': 'no-store', }); } const snapshot = part - ? scopedSnapshot(part, toWireWorkItem, running, parked, unstarted?.total) + ? // A reader asks for cards by id to hold the bodies a phases answer names by version. + scopedSnapshot(part, ids ? toVersionedWireWorkItem : toWireWorkItem, running, parked, unstarted?.total) : boardSnapshot(board, toWireWorkItem, running, parked, list.cursor); // Every open tab refetches its list on each feed frame; most frames leave it unchanged. - const headers = { ETag: snapshot.etag, 'Cache-Control': 'private, no-cache' }; - if (matchesEtag(c.req.header('if-none-match'), snapshot.etag)) { - return c.body(null, 304, { ...headers, Vary: 'Accept-Encoding' }); - } - return send(snapshot, headers); + return sendRevalidated(context, snapshot); }, }), @@ -607,6 +632,81 @@ export class WorkItemRoutes extends Route { }, }), + // ── What each phase of a board view lists, a page of it at a time ─────── + registerApiRoute(FACTORY_ROUTE_CONTRACTS.boardPhases.path, { + method: FACTORY_ROUTE_CONTRACTS.boardPhases.method, + requiresAuth: false, + handler: async c => { + const context = loose(c); + const resolved = await this.#resolveProject(context); + if ('response' in resolved) return resolved.response; + const path = FACTORY_ROUTE_CONTRACTS.boardPhases.pathSchema.safeParse({ + id: resolved.factoryProjectId, + boardKey: context.req.param('boardKey'), + }); + if (!path.success) return c.json({ error: 'board_not_found' }, 404); + const query = FACTORY_ROUTE_CONTRACTS.boardPhases.querySchema.safeParse({ + sort: context.req.query('sort'), + q: context.req.query('q'), + source: context.req.queries('source'), + linearProject: context.req.queries('linearProject'), + label: context.req.queries('label'), + teammate: context.req.queries('teammate'), + author: context.req.queries('author'), + assignee: context.req.queries('assignee'), + reviewer: context.req.queries('reviewer'), + worked: context.req.queries('worked'), + limit: context.req.query('limit'), + window: context.req.queries('window'), + item: context.req.query('item'), + cards: context.req.query('cards'), + }); + // A view that fails to parse must not answer as another view. + if (!query.success) return c.json({ error: 'invalid_phases_query' }, 400); + const { cards: withBodies, ...view } = query.data; + const project = { orgId: resolved.orgId, factoryProjectId: resolved.factoryProjectId }; + await workItems.ensureReady(); + const [list, boards] = await Promise.all([workItems.listShared(project), this.#boards.load(project)]); + const board = boards.get(path.data.boardKey); + if (!board) return c.json({ error: 'board_not_found' }, 404); + const phases = Object.keys(board.phases); + const { body, named } = boardPhases( + list, + { id: path.data.boardKey, phases }, + view, + resolved.userId, + wireVersion, + ); + const names = { + ...body, + runningSessionIds: sessionIdsWhere(named, sessionId => liveSessions.isRunning(sessionId)), + parkedSessionIds: sessionIdsWhere(named, sessionId => liveSessions.parked(sessionId) !== undefined), + }; + // The board asks again on each feed frame; most frames change nothing it shows. + return sendRevalidated( + context, + namedBody(names, withBodies ? () => ({ workItems: named.map(toVersionedWireWorkItem) }) : undefined), + ); + }, + }), + + // ── The labels and people the board's filter menus offer ──────────────── + registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemFilterOptions.path, { + method: FACTORY_ROUTE_CONTRACTS.workItemFilterOptions.method, + requiresAuth: false, + handler: async c => { + const context = loose(c); + const resolved = await this.#resolveProject(context); + if ('response' in resolved) return resolved.response; + await workItems.ensureReady(); + const list = await workItems.listShared({ + orgId: resolved.orgId, + factoryProjectId: resolved.factoryProjectId, + }); + return sendRevalidated(context, hashedBody(workItemFilterOptions(list))); + }, + }), + // ── Per-project queue-health age-threshold config (seconds) ───────────── registerApiRoute(FACTORY_ROUTE_CONTRACTS.healthThresholdsGet.path, { method: FACTORY_ROUTE_CONTRACTS.healthThresholdsGet.method, diff --git a/mastracode/factory/src/tools/messaging-tools.ts b/mastracode/factory/src/tools/messaging-tools.ts index 9bca01d67a8..2bffcbcb8fe 100644 --- a/mastracode/factory/src/tools/messaging-tools.ts +++ b/mastracode/factory/src/tools/messaging-tools.ts @@ -19,13 +19,13 @@ import type { LiveSessions } from '../session/live-sessions.js'; import type { AuditRecorder } from '../storage/domains/audit/domain.js'; import type { SourceControlSession } from '../storage/domains/source-control/base.js'; import type { WorkItemsStorage } from '../storage/domains/work-items/base.js'; +import { workItemNumber } from '../work-items/card-number.js'; import { FACTORY_SESSION_NOTIFICATION_SOURCE, deliverFactorySessionNotification, resolveSessionThread, } from './deliver.js'; import type { FactoryDeliveryController, FactoryDeliveryResult } from './deliver.js'; -import { workItemNumber } from './read-tools.js'; import { reportNotification, workItemReportAttributes, workItemReportRecipients } from './reports.js'; import { requirePerson } from './scope.js'; import type { FactoryToolScope } from './scope.js'; diff --git a/mastracode/factory/src/tools/read-tools.ts b/mastracode/factory/src/tools/read-tools.ts index 693301d4113..adb23b53438 100644 --- a/mastracode/factory/src/tools/read-tools.ts +++ b/mastracode/factory/src/tools/read-tools.ts @@ -28,7 +28,7 @@ import type { Card, WorkItemsStorage, } from '../storage/domains/work-items/base.js'; -import { CARD_NUMBER_METADATA_KEY } from '../work-items/create-work-item.js'; +import { workItemNumber } from '../work-items/card-number.js'; import { sessionActivity } from './deliver.js'; import type { FactorySessionActivity } from './deliver.js'; import type { FactoryMessaging } from './messaging-tools.js'; @@ -72,16 +72,6 @@ function iso(value: Date | string | null | undefined): string | null { return Number.isFinite(date.getTime()) ? date.toISOString() : null; } -/** The number a person sees on the card: the issue or PR number the item was filed from, or the project's own number for a card filed by hand. */ -export function workItemNumber(item: Pick): number | null { - const number = - item.workItem.metadata?.number ?? - item.workItem.metadata?.githubIssueNumber ?? - item.workItem.metadata?.githubPullRequestNumber ?? - item.metadata?.[CARD_NUMBER_METADATA_KEY]; - return typeof number === 'number' ? number : null; -} - export function workItemStage(item: Pick): string { return item.stages.join('+'); } diff --git a/mastracode/factory/src/tools/reports.ts b/mastracode/factory/src/tools/reports.ts index f194ba9aa6d..55d9dcbbf79 100644 --- a/mastracode/factory/src/tools/reports.ts +++ b/mastracode/factory/src/tools/reports.ts @@ -13,9 +13,9 @@ import type { import type { SourceControlSessionLookup } from '../session/factory-session.js'; import type { WorkItemsStorage } from '../storage/domains/work-items/base.js'; +import { workItemNumber } from '../work-items/card-number.js'; import { FACTORY_SESSION_NOTIFICATION_SOURCE } from './deliver.js'; import type { FactoryDeliveryResult, FactoryDeliveryTarget } from './deliver.js'; -import { workItemNumber } from './read-tools.js'; export type FactoryReportStatus = 'progress' | 'blocked' | 'done' | 'failed'; diff --git a/mastracode/factory/src/tools/session-tools.ts b/mastracode/factory/src/tools/session-tools.ts index 907d6273063..b59cbeabd22 100644 --- a/mastracode/factory/src/tools/session-tools.ts +++ b/mastracode/factory/src/tools/session-tools.ts @@ -32,9 +32,10 @@ import { effectiveModelScope } from '../storage/domains/projects/base.js'; import type { FactoryProjectsStorage } from '../storage/domains/projects/base.js'; import type { SourceControlStorageHandle } from '../storage/domains/source-control/base.js'; import type { Card, WorkItemsStorage } from '../storage/domains/work-items/base.js'; +import { workItemNumber } from '../work-items/card-number.js'; import { deliverFactorySessionNotification, resolveSessionThread } from './deliver.js'; import type { FactoryMessaging } from './messaging-tools.js'; -import { findWorkItem, workItemNotFound, workItemNumber, workItemRefSchema } from './read-tools.js'; +import { findWorkItem, workItemNotFound, workItemRefSchema } from './read-tools.js'; import { heartbeatOpenRunUntilEnd } from './run-watch.js'; import type { FactoryToolScope } from './scope.js'; import { sessionModel } from './side-sessions.js'; diff --git a/mastracode/factory/src/tools/side-sessions.ts b/mastracode/factory/src/tools/side-sessions.ts index d05ef3ef23c..478fa818b9c 100644 --- a/mastracode/factory/src/tools/side-sessions.ts +++ b/mastracode/factory/src/tools/side-sessions.ts @@ -2,9 +2,9 @@ import type { NotificationRecord, NotificationsStorage } from '@mastra/core/noti import type { SourceControlSessionLookup } from '../session/factory-session.js'; import type { Card, WorkItemsStorage } from '../storage/domains/work-items/base.js'; +import { workItemNumber } from '../work-items/card-number.js'; import { FACTORY_SESSION_NOTIFICATION_SOURCE, resolveSessionThread } from './deliver.js'; import type { FactoryDeliveryController } from './deliver.js'; -import { workItemNumber } from './read-tools.js'; import type { FactoryToolScope } from './scope.js'; /** Recent notifications scanned to find each side session's last report. */ diff --git a/mastracode/factory/src/tools/work-item-tools.ts b/mastracode/factory/src/tools/work-item-tools.ts index 670bddedf80..eb7589c58e1 100644 --- a/mastracode/factory/src/tools/work-item-tools.ts +++ b/mastracode/factory/src/tools/work-item-tools.ts @@ -22,6 +22,7 @@ import { resolveWorkItemRepository } from '../session/work-item-repository.js'; import type { AuditRecorder } from '../storage/domains/audit/domain.js'; import { WorkItemRelationError } from '../storage/domains/work-items/base.js'; import type { UpdateWorkItemInput, Card, WorkItemsStorage } from '../storage/domains/work-items/base.js'; +import { workItemNumber } from '../work-items/card-number.js'; import { createFactoryWorkItem } from '../work-items/create-work-item.js'; import type { FactoryAuditEmit } from '../work-items/create-work-item.js'; import { @@ -30,15 +31,7 @@ import { retryFactoryDecision, } from '../work-items/decision-actions.js'; import type { FactoryDecisionActionResult } from '../work-items/decision-actions.js'; -import { - MAX_TEXT, - findWorkItem, - workItemRefSchema, - truncate, - workItemNotFound, - workItemNumber, - workItemStage, -} from './read-tools.js'; +import { MAX_TEXT, findWorkItem, workItemRefSchema, truncate, workItemNotFound, workItemStage } from './read-tools.js'; import { requirePerson } from './scope.js'; import type { FactoryToolScope } from './scope.js'; diff --git a/mastracode/factory/src/work-items/board-filter-options.ts b/mastracode/factory/src/work-items/board-filter-options.ts new file mode 100644 index 00000000000..92aff403b4a --- /dev/null +++ b/mastracode/factory/src/work-items/board-filter-options.ts @@ -0,0 +1,36 @@ +import type { WorkItemFilterOptionsResponse } from '../routes/contracts.js'; +import type { Card } from '../storage/domains/work-items/base.js'; +import { cardFacts } from './card-facts.js'; +import type { ProviderPerson } from './card-people.js'; + +// One answer per list version: `listShared` returns the same array until a card changes. +const optionsByList = new WeakMap(); + +/** What the board's filter menus offer, read over every card of the project's `list`. */ +export function workItemFilterOptions(list: readonly Card[]): WorkItemFilterOptionsResponse { + let options = optionsByList.get(list); + if (options) return options; + const labels = new Set(); + const people = new Map(); + const actorIds = new Set(); + for (const card of list) { + const facts = cardFacts(card); + for (const label of facts.labels) labels.add(label); + for (const actorId of facts.humanActorIds) actorIds.add(actorId); + for (const named of Object.values(facts.people)) { + for (const person of named) { + // One person is named with the casing of the first card that names them. + if (!people.has(person.id)) people.set(person.id, person); + } + } + } + options = { + labels: [...labels].sort((left, right) => left.localeCompare(right)), + people: [...people.values()].sort( + (left, right) => left.name.localeCompare(right.name) || left.id.localeCompare(right.id), + ), + actorIds: [...actorIds].sort(), + }; + optionsByList.set(list, options); + return options; +} diff --git a/mastracode/factory/src/work-items/board-phases.test.ts b/mastracode/factory/src/work-items/board-phases.test.ts new file mode 100644 index 00000000000..c761c3657bf --- /dev/null +++ b/mastracode/factory/src/work-items/board-phases.test.ts @@ -0,0 +1,298 @@ +import { describe, expect, it } from 'vitest'; + +import { boardPhasesQuerySchema } from '../routes/contracts.js'; +import { testCard } from '../routes/test-utils.js'; +import type { Card } from '../storage/domains/work-items/base.js'; +import { workItemFilterOptions } from './board-filter-options.js'; +import { boardPhases } from './board-phases.js'; + +const BOARD = { id: 'work', phases: ['intake', 'planning', 'done'] }; +// The route names a card by the body it sends; nothing here reads the name. +const version = (card: Card) => `version of ${card.id}`; + +/** The view a reader's query string asks for, parsed as the route parses it. */ +function view(query: Record = {}) { + const { cards: _cards, ...parsed } = boardPhasesQuerySchema.parse(query); + return parsed; +} + +function listedIds(list: readonly Card[], query: Record = {}, userId = 'u1') { + const { body } = boardPhases(list, BOARD, view(query), userId, version); + return Object.fromEntries(body.phases.map(entry => [entry.phase, entry.cards.map(card => card.id)])); +} + +const entered = (stage: string, enteredAt: string, by = 'u1') => ({ stage, enteredAt, by }); + +describe('boardPhases', () => { + it('orders a phase by each card’s latest entry into it, not its first', () => { + const cameBack = testCard('came-back', { + stages: ['planning'], + stageHistory: [ + entered('planning', '2026-03-01T00:00:00.000Z'), + entered('intake', '2026-03-02T00:00:00.000Z'), + entered('planning', '2026-03-05T00:00:00.000Z'), + ], + }); + const stayed = testCard('stayed', { + stages: ['planning'], + stageHistory: [entered('planning', '2026-03-03T00:00:00.000Z')], + }); + + expect(listedIds([stayed, cameBack]).planning).toEqual(['came-back', 'stayed']); + }); + + it('places a card that never entered its phase by when it was created', () => { + const noHistory = testCard('no-history', { createdAt: new Date('2026-03-04T00:00:00.000Z') }); + const before = testCard('before', { stageHistory: [entered('intake', '2026-03-03T00:00:00.000Z')] }); + const after = testCard('after', { stageHistory: [entered('intake', '2026-03-05T00:00:00.000Z')] }); + + expect(listedIds([before, noHistory, after]).intake).toEqual(['after', 'no-history', 'before']); + }); + + it('puts first the cards the reader last moved into the phase, each group in recent order', () => { + const list = [ + testCard('a', { stageHistory: [entered('intake', '2026-03-01T00:00:00.000Z', 'u1')] }), + testCard('b', { stageHistory: [entered('intake', '2026-03-02T00:00:00.000Z', 'u2')] }), + testCard('c', { stageHistory: [entered('intake', '2026-03-03T00:00:00.000Z', 'u1')] }), + // Moved here by u1 first, then by u2: the latest entry decides whose it is. + testCard('d', { + stageHistory: [ + entered('intake', '2026-03-01T12:00:00.000Z', 'u1'), + entered('intake', '2026-03-04T00:00:00.000Z', 'u2'), + ], + }), + ]; + + expect(listedIds(list, { sort: 'recent-mine' }, 'u1').intake).toEqual(['c', 'a', 'd', 'b']); + expect(listedIds(list, { sort: 'recent-mine' }, 'u2').intake).toEqual(['d', 'b', 'c', 'a']); + expect(listedIds(list, { sort: 'recent-mine', limit: '1' }, 'u2').intake).toEqual(['d']); + }); + + it('breaks a tie on the creation instant by id, descending, in both creation orders', () => { + // Entered in the opposite order, so the creation orders cannot inherit theirs from `recent`. + const list = [ + testCard('a', { stageHistory: [entered('intake', '2026-03-03T00:00:00.000Z')] }), + testCard('b', { stageHistory: [entered('intake', '2026-03-02T00:00:00.000Z')] }), + testCard('c', { stageHistory: [entered('intake', '2026-03-01T00:00:00.000Z')] }), + ]; + + expect(listedIds(list, {}).intake).toEqual(['a', 'b', 'c']); + expect(listedIds(list, { sort: 'created-newest' }).intake).toEqual(['c', 'b', 'a']); + expect(listedIds(list, { sort: 'created-oldest' }).intake).toEqual(['c', 'b', 'a']); + }); + + it('lists the same cards under the phases the board has now, once the board loses a phase', () => { + const list = [testCard('kept', { stages: ['intake'] }), testCard('moved', { stages: ['planning'] })]; + const read = (phases: string[]) => + boardPhases(list, { id: 'work', phases }, view(), 'u1', version).body.phases.map(entry => [ + entry.phase, + entry.cards.map(card => card.id), + ]); + + expect(read(['intake', 'planning'])).toEqual([ + ['intake', ['kept']], + ['planning', ['moved']], + ]); + // The edited board keeps its id; a card of the phase it lost is listed under the first one. + expect(read(['intake'])).toEqual([['intake', ['moved', 'kept']]]); + }); + + it('names the first `limit` cards related to one listed card, and counts them all', () => { + const children = ['c1', 'c2', 'c3', 'c4', 'c5'].map(id => + testCard(id, { board: 'other', parentWorkItemId: 'parent' }), + ); + const list = [testCard('parent'), ...children, testCard('alone')]; + + const { body, named } = boardPhases(list, BOARD, view({ limit: '2' }), 'u1', version); + + expect(body.related.map(card => card.id)).toEqual(['c1', 'c2']); + expect(body.relatedTotal).toBe(5); + expect(named.map(card => card.id)).toEqual(['parent', 'alone', 'c1', 'c2']); + }); + + describe('asked for a card (item)', () => { + const cardId = (nth: number) => `00000000-0000-4000-8000-${String(nth).padStart(12, '0')}`; + /** `count` cards of one phase; the lower the number, the longer ago it entered. */ + const aged = (count: number, phase = 'intake') => + Array.from({ length: count }, (_, nth) => + testCard(cardId(nth), { + title: nth % 2 === 0 ? `Fix ${nth}` : `Rename ${nth}`, + stages: [phase], + createdAt: new Date(Date.UTC(2026, 0, 1) + nth * 1_000), + stageHistory: [entered(phase, new Date(Date.UTC(2026, 2, 1) + nth * 1_000).toISOString())], + }), + ); + const ask = (list: readonly Card[], query: Record) => + boardPhases(list, BOARD, view(query), 'u1', version); + + it('names the card with its place in the phase, and lists the phase no deeper for it', () => { + const list = aged(4); + + const { body, named } = ask(list, { limit: '1', item: cardId(0) }); + + expect(body.phases[0]?.cards.map(card => card.id)).toEqual([cardId(3)]); + expect(body.item).toEqual({ + id: cardId(0), + version: `version of ${cardId(0)}`, + places: [{ phase: 'intake', position: 3 }], + }); + expect(named.map(card => card.id)).toEqual([cardId(3), cardId(0)]); + }); + + it('counts the place in the view’s order and among the cards the view keeps', () => { + const list = aged(4); + + expect(ask(list, { item: cardId(0), sort: 'created-oldest' }).body.item?.places).toEqual([ + { phase: 'intake', position: 0 }, + ]); + // Cards 2 and 0 match `fix`; card 2 entered later. + expect(ask(list, { item: cardId(0), q: 'fix' }).body.item?.places).toEqual([{ phase: 'intake', position: 1 }]); + }); + + it('gives a card the view filters out no place, and still names it for its body', () => { + const list = aged(4); + + const { body, named } = ask(list, { limit: '1', item: cardId(0), q: 'rename' }); + + expect(body.item).toMatchObject({ id: cardId(0), places: [] }); + expect(body.phases[0]).toMatchObject({ total: 2, cards: [{ id: cardId(3) }] }); + expect(named.map(card => card.id)).toEqual([cardId(3), cardId(0)]); + }); + + it('gives a card in two phases a place in each', () => { + const list = [...aged(3), { ...aged(1, 'planning')[0]!, id: cardId(9), stages: ['intake', 'planning'] }]; + + expect(ask(list, { item: cardId(9) }).body.item?.places).toEqual([ + { phase: 'intake', position: 3 }, + { phase: 'planning', position: 0 }, + ]); + }); + + it('answers nothing for a card the board does not hold', () => { + const list = [...aged(2), testCard(cardId(7), { board: 'other' })]; + + const { body, named } = ask(list, { item: cardId(7) }); + + expect(body).not.toHaveProperty('item'); + expect(named.map(card => card.id)).toEqual([cardId(1), cardId(0)]); + }); + + it('names the cards related to the asked card', () => { + const [oldest, ...rest] = aged(3); + const parent = testCard('parent', { board: 'other' }); + const list = [parent, { ...oldest!, parentWorkItemId: 'parent' }, ...rest]; + + const { body } = ask(list, { limit: '1', item: cardId(0) }); + + expect(body.related.map(card => card.id)).toEqual(['parent']); + }); + + // A link to an old card used to list its whole phase above it: 82% of a 10,000-card board. + it.each([2_000, 10_000])('names no more cards for the oldest of %i than for one on the first page', count => { + const list = aged(count, 'done'); + const shallow = ask(list, { item: cardId(count - 1) }); + const deep = ask(list, { item: cardId(0) }); + + expect(deep.body.item?.places).toEqual([{ phase: 'done', position: count - 1 }]); + expect(shallow.named).toHaveLength(50); + // The asked card is the one more. + expect(deep.named).toHaveLength(51); + expect(deep.body.phases).toEqual(shallow.body.phases); + }); + }); + + it('deepens a phase whose id is as long as a board allows', () => { + const longest = 'p'.repeat(128); + const list = [testCard('a', { stages: [longest] }), testCard('b', { stages: [longest] })]; + + const { body } = boardPhases( + list, + { id: 'work', phases: [longest] }, + view({ limit: '1', window: [`${longest}:2`] }), + 'u1', + version, + ); + + expect(body.phases[0]?.cards.map(card => card.id)).toEqual(['b', 'a']); + }); + + it('shows a card held by none of the board’s phases under the first one only', () => { + const { body } = boardPhases([testCard('lost', { stages: ['retired-lane'] })], BOARD, view(), 'u1', version); + + expect(body.phases.map(entry => [entry.phase, entry.total])).toEqual([ + ['intake', 1], + ['planning', 0], + ['done', 0], + ]); + }); + + it('files a Slack thread under Slack, not under cards filed by hand', () => { + const list = [ + testCard('by-hand'), + testCard('thread', { externalSource: { integrationId: 'slack', type: 'slack-thread', externalId: 'C1:1.2' } }), + ]; + + expect(listedIds(list, { source: ['manual'] }).intake).toEqual(['by-hand']); + expect(listedIds(list, { source: ['slack'] }).intake).toEqual(['thread']); + }); + + it('counts as having worked on a card whoever filed it, moved it in or out, or started a session on it', () => { + const list = [ + testCard('filed', { createdBy: 'u2' }), + testCard('left', { + createdBy: 'factory', + stageHistory: [{ ...entered('planning', '2026-03-01T00:00:00.000Z', 'agent:triage'), exitedBy: 'u2' }], + }), + testCard('started', { + createdBy: 'factory', + sessions: { execute: { sessionId: 's1', branch: 'factory/1', threadId: 't1', startedBy: 'u2' } }, + }), + testCard('automation', { createdBy: 'factory' }), + testCard('other', { createdBy: 'u3' }), + ]; + + expect(listedIds(list, { worked: ['factory:u2'] }).intake.toSorted()).toEqual(['filed', 'left', 'started']); + }); + + it('names as author the person who filed a card by hand, and no Factory user for a provider’s card', () => { + const list = [ + testCard('by-hand', { createdBy: 'u2' }), + testCard('synced', { + createdBy: 'u2', + externalSource: { integrationId: 'github', type: 'issue', externalId: '7' }, + workItem: { ...testCard('synced').workItem, provider: 'github', author: 'octocat' }, + }), + ]; + + expect(listedIds(list, { author: ['factory:u2'] }).intake).toEqual(['by-hand']); + expect(listedIds(list, { author: ['github:octocat'] }).intake).toEqual(['synced']); + }); + + it('names every card of the answer once, listed cards before related ones', () => { + const parent = testCard('parent', { stageHistory: [entered('intake', '2026-03-01T00:00:00.000Z')] }); + const child = testCard('child', { + parentWorkItemId: 'parent', + stageHistory: [entered('intake', '2026-03-02T00:00:00.000Z')], + }); + + const { body, named } = boardPhases([parent, child], BOARD, view({ limit: '1' }), 'u1', version); + + expect(body.related).toEqual([{ id: 'parent', version: 'version of parent' }]); + expect(named.map(card => card.id)).toEqual(['child', 'parent']); + }); +}); + +describe('workItemFilterOptions', () => { + it('offers one entry per person, however many cards name them and in whatever case', () => { + const issue = (id: string, author: string) => + testCard(id, { + externalSource: { integrationId: 'github', type: 'issue', externalId: id }, + workItem: { ...testCard(id).workItem, provider: 'github', author }, + }); + + expect(workItemFilterOptions([issue('1', 'Octocat'), issue('2', 'octocat'), issue('3', 'hubot')]).people).toEqual([ + { id: 'github:hubot', name: 'hubot', source: 'github' }, + { id: 'github:octocat', name: 'Octocat', source: 'github' }, + ]); + }); +}); diff --git a/mastracode/factory/src/work-items/board-phases.ts b/mastracode/factory/src/work-items/board-phases.ts new file mode 100644 index 00000000000..2077c807983 --- /dev/null +++ b/mastracode/factory/src/work-items/board-phases.ts @@ -0,0 +1,231 @@ +/** + * What one board view shows: for each phase of the board, the cards a reader lists and how many + * match. The phases route answers with it, and the browser's tests run it in place of the server, + * so it reads plain values only. + */ + +import { boardForWorkItem } from '../boards/semantics.js'; +import type { BoardPhasesQuery, BoardPhasesResponse } from '../routes/contracts.js'; +import type { Card } from '../storage/domains/work-items/base.js'; +import { cardFacts } from './card-facts.js'; +import { hasEveryLabel } from './card-labels.js'; +import { BOARD_PERSON_FIELDS, matchesPeople } from './card-people.js'; +import { matchesSourceFilters } from './card-source-filters.js'; +import { relatedCardsIn } from './list-related-cards.js'; +import { hasEveryWord, searchWords } from './search-words.js'; + +/** The board whose phases are read: its id and its phases in declaration order. */ +export interface PhasesBoard { + id: string; + phases: readonly string[]; +} + +/** The view, as the phases route parses it. `cards` is the route's own: bodies are not computed here. */ +export type BoardPhasesView = Omit; + +export interface BoardPhases { + /** The answer, without what only the route knows: session states and card bodies. */ + body: Pick; + /** Every card `body` names: the listed ones, the asked one, then the related ones. */ + named: Card[]; +} + +/** A card in one phase. */ +interface Placed { + card: Card; + /** When the card last entered the phase; when it was created, for a card the phase holds without an entry. */ + at: string; + /** Who made that entry. */ + by: string | undefined; +} + +interface PhaseCards { + phase: string; + /** Latest entry first. */ + recent: Placed[]; + newest?: Placed[]; + oldest?: Placed[]; +} + +interface BoardIndex { + /** The board's cards, each once. */ + cards: Card[]; + phases: PhaseCards[]; + /** A card once for each phase it is listed under beyond its first. */ + repeats: Card[]; +} + +// One index per list version and board: `listShared` returns the same array until a card changes. +const boardsByList = new WeakMap>(); + +/** The phases that list the card: each of the board's phases it is in, or the first one when it is in none. */ +function cardPhases(card: Card, phases: readonly string[]): readonly string[] { + const held = phases.filter(phase => card.stages.includes(phase)); + return held.length > 0 ? held : phases.slice(0, 1); +} + +function placed(card: Card, phase: string): Placed { + let latest: Card['stageHistory'][number] | undefined; + for (const entry of card.stageHistory) { + if (entry.stage === phase && (!latest || entry.enteredAt > latest.enteredAt)) latest = entry; + } + return { card, at: latest?.enteredAt ?? card.createdAt.toISOString(), by: latest?.by }; +} + +function descending(left: string, right: string): number { + return left < right ? 1 : left > right ? -1 : 0; +} + +// Cards that entered at the same instant keep one order on every read. +function byRecent(left: Placed, right: Placed): number { + return descending(left.at, right.at) || descending(left.card.id, right.card.id); +} + +function byCreation(direction: 1 | -1): (left: Placed, right: Placed) => number { + return (left, right) => + direction * (left.card.createdAt.getTime() - right.card.createdAt.getTime()) || + descending(left.card.id, right.card.id); +} + +function boardIndex(list: readonly Card[], board: PhasesBoard): BoardIndex { + let boards = boardsByList.get(list); + if (!boards) boardsByList.set(list, (boards = new Map())); + // The phases are part of the key: an edited board keeps its id. + const key = [board.id, ...board.phases].join('\n'); + let index = boards.get(key); + if (index) return index; + + const byPhase = new Map(board.phases.map((phase): [string, Placed[]] => [phase, []])); + const cards: Card[] = []; + const repeats: Card[] = []; + for (const card of list) { + if (boardForWorkItem(card) !== board.id) continue; + cards.push(card); + cardPhases(card, board.phases).forEach((phase, nth) => { + byPhase.get(phase)?.push(placed(card, phase)); + if (nth > 0) repeats.push(card); + }); + } + index = { + cards, + phases: [...byPhase].map(([phase, entries]) => ({ phase, recent: entries.sort(byRecent) })), + repeats, + }; + boards.set(key, index); + return index; +} + +function ordered(held: PhaseCards, sort: BoardPhasesView['sort']): readonly Placed[] { + if (sort === 'created-newest') return (held.newest ??= held.recent.toSorted(byCreation(-1))); + if (sort === 'created-oldest') return (held.oldest ??= held.recent.toSorted(byCreation(1))); + return held.recent; +} + +/** Whether the view's search and filters keep a card; undefined when the view has none. */ +function viewMatcher(view: BoardPhasesView): ((card: Card) => boolean) | undefined { + const words = searchWords(view.q ?? ''); + const bySource = view.source.size > 0 || view.linearProject.size > 0; + const byLabel = view.label.size > 0; + const byPeople = BOARD_PERSON_FIELDS.some(field => view[field].size > 0); + if (words.length === 0 && !bySource && !byLabel && !byPeople) return undefined; + return card => { + const facts = cardFacts(card); + return ( + hasEveryWord(facts.text, words) && + (!bySource || matchesSourceFilters(facts, view)) && + (!byLabel || hasEveryLabel(facts.labels, view.label)) && + (!byPeople || matchesPeople(facts.relations, view)) + ); + }; +} + +const EVERY_CARD: ReadonlyArray<(entry: Placed) => boolean> = [() => true]; + +/** + * The phases of `board` as `view` shows them to `userId`, read from the project's whole `list`. + * A window for a phase the board does not have deepens nothing: a reader may still hold a + * phase deeper after the board lost that phase, and keeps its board. `version` names the body the + * caller sends for a card: the caller knows that body, this module does not. + */ +export function boardPhases( + list: readonly Card[], + board: PhasesBoard, + view: BoardPhasesView, + userId: string, + version: (card: Card) => string, +): BoardPhases { + const stamp = (card: Card) => ({ id: card.id, version: version(card) }); + const index = boardIndex(list, board); + const matches = viewMatcher(view); + // `recent-mine` is `recent` read twice: the cards the reader last moved here, then the others. + const passes = + view.sort === 'recent-mine' + ? [(entry: Placed) => entry.by === userId, (entry: Placed) => entry.by !== userId] + : EVERY_CARD; + const item = view.item === undefined ? undefined : index.cards.find(card => card.id === view.item); + const shown = item && (!matches || matches(item)) ? cardPhases(item, board.phases) : []; + const places: Array<{ phase: string; position: number }> = []; + + const listed = new Set(); + let matchingTotal = 0; + const phases = index.phases.map(held => { + const all = ordered(held, view.sort); + const size = view.window.get(held.phase) ?? view.limit; + // The asked card is found, not listed down to: the answer is no larger for a card that lies deep. + let sought = shown.includes(held.phase) ? item : undefined; + const cards: Card[] = []; + let total = 0; + scan: for (const pass of passes) { + for (const entry of all) { + if (!pass(entry) || (matches && !matches(entry.card))) continue; + if (entry.card === sought) { + places.push({ phase: held.phase, position: total }); + sought = undefined; + } + total += 1; + if (cards.length < size) { + cards.push(entry.card); + listed.add(entry.card); + } else if (!matches && !sought) { + // Nothing is filtered out, so the rest need not be read to count them. + break scan; + } + } + } + if (!matches) total = all.length; + matchingTotal += total; + return { phase: held.phase, total, cards: cards.map(stamp) }; + }); + for (const card of index.repeats) { + if (!matches || matches(card)) matchingTotal -= 1; + } + // Its body is the reader's to show whether or not a phase lists it. + if (item) listed.add(item); + + const relatedTo = relatedCardsIn(list); + const related = new Set(); + const everyRelated = new Set(); + for (const card of listed) { + // One card may be the parent of thousands: each names its first `limit`, and the total counts the rest. + let named = 0; + for (const other of relatedTo(card)) { + if (listed.has(other)) continue; + everyRelated.add(other); + if (named < view.limit) { + related.add(other); + named += 1; + } + } + } + return { + body: { + phases, + ...(item ? { item: { ...stamp(item), places } } : {}), + related: [...related].map(stamp), + relatedTotal: everyRelated.size, + boardTotal: index.cards.length, + matchingTotal, + }, + named: [...listed, ...related], + }; +} diff --git a/mastracode/factory/src/work-items/card-facts.ts b/mastracode/factory/src/work-items/card-facts.ts new file mode 100644 index 00000000000..20dbdf3780c --- /dev/null +++ b/mastracode/factory/src/work-items/card-facts.ts @@ -0,0 +1,88 @@ +import { hasPullRequest } from '../boards/semantics.js'; +import { isHumanActorId } from '../storage/domains/audit/actors.js'; +import type { Card } from '../storage/domains/work-items/base.js'; +import { workItemBranchSource } from '../work-item-branch.js'; +import type { WorkItemBranchSource } from '../work-item-branch.js'; +import { metadataLabels } from './card-labels.js'; +import { factoryParticipantId, providerPeople } from './card-people.js'; +import type { BoardRelations, ProviderPerson, ProviderPersonRole } from './card-people.js'; +import { cardSearchText } from './card-search-text.js'; +import type { SourceFacts } from './card-source-filters.js'; + +/** What a board view's search and filters read of a card. */ +export interface CardFacts extends SourceFacts { + hasPullRequest: boolean; + labels: ReadonlySet; + /** The people the card's source names. */ + people: Record; + /** Participant ids by role: the source's people, and the Factory users who worked on the card. */ + relations: BoardRelations; + /** The Factory users who created the card, moved it or started a session on it. */ + humanActorIds: readonly string[]; + /** Lowercased, so a search lowercases only its own words. */ + text: string; +} + +// A card object never changes: `listShared` gives a changed card a new object. +const factsByCard = new WeakMap(); + +/** + * What the card's source says of it. A card no provider filed has no source: its facts are its + * work item's with the card's own on top, as clients read them. + */ +export function sourceMetadata({ workItem, metadata }: Card): Record { + if (workItem.provider === 'factory') return { ...workItem.metadata, ...metadata }; + return { + ...workItem.metadata, + labels: workItem.labels, + author: workItem.author, + state: workItem.state, + identifier: workItem.key, + }; +} + +function humanActorIds(card: Card): string[] { + const ids = new Set(); + const add = (actorId: string | undefined) => { + if (isHumanActorId(actorId)) ids.add(actorId); + }; + add(card.createdBy); + for (const entry of card.stageHistory) { + add(entry.by); + add(entry.exitedBy); + } + for (const session of Object.values(card.sessions)) add(session.startedBy); + return [...ids]; +} + +/** The card's facts, computed once for every view that reads the card. */ +export function cardFacts(card: Card): CardFacts { + let facts = factsByCard.get(card); + if (facts) return facts; + // A Slack thread is its own source on the board, not a card filed by hand. + const source: WorkItemBranchSource = + card.externalSource?.integrationId === 'slack' ? 'slack-thread' : workItemBranchSource(card.externalSource); + const metadata = sourceMetadata(card); + const people = providerPeople({ source, metadata }); + const actorIds = humanActorIds(card); + const authored = new Set(people.authored.map(person => person.id)); + // A card filed by hand has no source to name its author: the person who filed it is. + if (source === 'manual' && isHumanActorId(card.createdBy)) authored.add(factoryParticipantId(card.createdBy)); + facts = { + source, + metadata, + hasPullRequest: hasPullRequest({ source, workItem: card.workItem }), + labels: new Set(metadataLabels(metadata)), + people, + relations: { + worked: new Set(actorIds.map(factoryParticipantId)), + authored, + assigned: new Set(people.assigned.map(person => person.id)), + 'review-requested': new Set(people['review-requested'].map(person => person.id)), + }, + humanActorIds: actorIds, + text: cardSearchText(card), + }; + factsByCard.set(card, facts); + return facts; +} diff --git a/mastracode/factory/src/work-items/card-labels.ts b/mastracode/factory/src/work-items/card-labels.ts new file mode 100644 index 00000000000..da6193eb8e7 --- /dev/null +++ b/mastracode/factory/src/work-items/card-labels.ts @@ -0,0 +1,14 @@ +/** The labels a source put on an item. */ +export function metadataLabels(metadata: Record): string[] { + return Array.isArray(metadata.labels) + ? metadata.labels.filter((label): label is string => typeof label === 'string') + : []; +} + +/** Whether the item carries every picked label. */ +export function hasEveryLabel(labels: ReadonlySet, picked: Iterable): boolean { + for (const label of picked) { + if (!labels.has(label)) return false; + } + return true; +} diff --git a/mastracode/factory/src/work-items/card-number.ts b/mastracode/factory/src/work-items/card-number.ts new file mode 100644 index 00000000000..199627655e9 --- /dev/null +++ b/mastracode/factory/src/work-items/card-number.ts @@ -0,0 +1,18 @@ +import type { Card } from '../storage/domains/work-items/base.js'; + +/** + * Board metadata key holding the `#number` of a card filed without an issue + * behind it. Kept apart from `number`, which integrations read as the source + * issue's number. + */ +export const CARD_NUMBER_METADATA_KEY = 'cardNumber'; + +/** The number a person sees on the card: the issue or PR number the item was filed from, or the project's own number for a card filed by hand. */ +export function workItemNumber(item: Pick): number | null { + const number = + item.workItem.metadata?.number ?? + item.workItem.metadata?.githubIssueNumber ?? + item.workItem.metadata?.githubPullRequestNumber ?? + item.metadata?.[CARD_NUMBER_METADATA_KEY]; + return typeof number === 'number' ? number : null; +} diff --git a/mastracode/factory/src/work-items/card-people.test.ts b/mastracode/factory/src/work-items/card-people.test.ts new file mode 100644 index 00000000000..949659636a3 --- /dev/null +++ b/mastracode/factory/src/work-items/card-people.test.ts @@ -0,0 +1,132 @@ +import { describe, expect, it } from 'vitest'; + +import { matchesPeople, providerPeople } from './card-people.js'; +import type { BoardPeopleFilters, BoardRelations } from './card-people.js'; + +const NO_ONE = { authored: [], assigned: [], 'review-requested': [] }; + +function picked(filters: Partial>): BoardPeopleFilters { + return { + teammate: new Set(filters.teammate), + author: new Set(filters.author), + assignee: new Set(filters.assignee), + reviewer: new Set(filters.reviewer), + worked: new Set(filters.worked), + }; +} + +function relations(byRole: Partial>): BoardRelations { + return { + worked: new Set(byRole.worked), + authored: new Set(byRole.authored), + assigned: new Set(byRole.assigned), + 'review-requested': new Set(byRole['review-requested']), + }; +} + +describe('providerPeople', () => { + it('names a GitHub pull request’s author, assignees and requested reviewers, with ids that ignore case', () => { + const people = providerPeople({ + source: 'github-pr', + metadata: { author: 'Octocat', assignees: ['Hubot', 'monalisa'], requestedReviewers: ['Defunkt'] }, + }); + + expect(people).toEqual({ + authored: [{ id: 'github:octocat', name: 'Octocat', source: 'github' }], + assigned: [ + { id: 'github:hubot', name: 'Hubot', source: 'github' }, + { id: 'github:monalisa', name: 'monalisa', source: 'github' }, + ], + 'review-requested': [{ id: 'github:defunkt', name: 'Defunkt', source: 'github' }], + }); + }); + + it('names a single assignee once when the source lists them both ways', () => { + const people = providerPeople({ + source: 'gitlab-issue', + metadata: { assignees: ['hubot'], assignee: 'hubot' }, + }); + + expect(people.assigned).toEqual([{ id: 'gitlab:hubot', name: 'hubot', source: 'gitlab' }]); + }); + + it('asks no review of an issue, whatever its metadata says', () => { + const people = providerPeople({ source: 'github-issue', metadata: { requestedReviewers: ['defunkt'] } }); + + expect(people['review-requested']).toEqual([]); + }); + + it.each([ + ['its creator', { creator: 'Ada', linearCreator: 'Grace', author: 'Linus' }, 'Ada'], + ['its Linear creator when it names no creator', { linearCreator: 'Grace', author: 'Linus' }, 'Grace'], + ['its author when it names neither', { author: 'Linus' }, 'Linus'], + ])('reads the author of a Linear issue from %s', (_case, metadata, name) => { + expect(providerPeople({ source: 'linear-issue', metadata }).authored).toEqual([ + { id: `linear:${name.toLowerCase()}`, name, source: 'linear' }, + ]); + }); + + it('reads the one assignee of a Jira issue or an incident.io follow-up', () => { + expect(providerPeople({ source: 'jira-issue', metadata: { assignee: 'Ada' } }).assigned).toEqual([ + { id: 'jira:ada', name: 'Ada', source: 'jira' }, + ]); + expect(providerPeople({ source: 'incidentio-follow-up', metadata: { linearAssignee: 'Grace' } }).assigned).toEqual([ + { id: 'incidentio:grace', name: 'Grace', source: 'incidentio' }, + ]); + }); + + it('drops blank and non-text names, and trims the others', () => { + const people = providerPeople({ + source: 'github-issue', + metadata: { author: ' ', assignees: [' hubot ', '', 7, null] }, + }); + + expect(people.authored).toEqual([]); + expect(people.assigned).toEqual([{ id: 'github:hubot', name: 'hubot', source: 'github' }]); + }); + + it.each(['manual', 'slack-thread'] as const)('names no one for a %s card', source => { + expect(providerPeople({ source, metadata: { author: 'octocat', assignee: 'hubot' } })).toEqual(NO_ONE); + }); +}); + +describe('matchesPeople', () => { + const card = relations({ + worked: ['factory:u1'], + authored: ['github:octocat'], + assigned: ['github:hubot'], + 'review-requested': ['github:defunkt'], + }); + + it('keeps every card when no person is picked', () => { + expect(matchesPeople(relations({}), picked({}))).toBe(true); + }); + + it.each([ + ['author', 'github:octocat'], + ['assignee', 'github:hubot'], + ['reviewer', 'github:defunkt'], + ['worked', 'factory:u1'], + ] as const)('matches the %s filter on that role only', (field, id) => { + expect(matchesPeople(card, picked({ [field]: [id] }))).toBe(true); + // The same person picked under another role is someone else's card. + const other = field === 'author' ? 'assignee' : 'author'; + expect(matchesPeople(card, picked({ [other]: [id] }))).toBe(false); + }); + + it('matches the teammate filter on any role', () => { + for (const id of ['factory:u1', 'github:octocat', 'github:hubot', 'github:defunkt']) { + expect(matchesPeople(card, picked({ teammate: [id] }))).toBe(true); + } + expect(matchesPeople(card, picked({ teammate: ['github:stranger'] }))).toBe(false); + }); + + it('needs one of the picked people in a field, and every field to match', () => { + expect(matchesPeople(card, picked({ author: ['github:stranger', 'github:octocat'] }))).toBe(true); + expect(matchesPeople(card, picked({ author: ['github:octocat'], assignee: ['github:stranger'] }))).toBe(false); + }); + + it('compares ids as sent', () => { + expect(matchesPeople(card, picked({ author: ['github:Octocat'] }))).toBe(false); + }); +}); diff --git a/mastracode/factory/src/work-items/card-people.ts b/mastracode/factory/src/work-items/card-people.ts new file mode 100644 index 00000000000..bab1735b4d8 --- /dev/null +++ b/mastracode/factory/src/work-items/card-people.ts @@ -0,0 +1,119 @@ +import type { WorkItemBranchSource } from '../work-item-branch.js'; +import type { SourceFacts } from './card-source-filters.js'; + +/** How a person relates to a card. `worked` is Factory's own record; the others are what the source says. */ +export const BOARD_PERSON_ROLES = ['worked', 'authored', 'assigned', 'review-requested'] as const; +export type BoardPersonRole = (typeof BOARD_PERSON_ROLES)[number]; +export type ProviderPersonRole = Exclude; + +/** One filter per person role, plus `teammate` (shown as Involves) for any role. */ +export const BOARD_PERSON_FIELDS = ['teammate', 'author', 'assignee', 'reviewer', 'worked'] as const; +export type BoardPersonFieldId = (typeof BOARD_PERSON_FIELDS)[number]; + +const PERSON_FIELD_ROLES: Record = { + teammate: BOARD_PERSON_ROLES, + author: ['authored'], + assignee: ['assigned'], + reviewer: ['review-requested'], + worked: ['worked'], +}; + +/** The participant ids related to a card, by role. */ +export type BoardRelations = Record>; +export type BoardPeopleFilters = Record>; + +export type ProviderPersonSource = 'github' | 'gitlab' | 'linear' | 'jira' | 'incidentio'; + +/** A person as a source names them. The id is `:`. */ +export interface ProviderPerson { + id: string; + name: string; + source: ProviderPersonSource; +} + +/** The participant id of a Factory user. */ +export function factoryParticipantId(userId: string): string { + return `factory:${userId}`; +} + +/** The provider whose people a source names; undefined for a card no provider filed. */ +function personSource(source: WorkItemBranchSource): ProviderPersonSource | undefined { + switch (source) { + case 'github-issue': + case 'github-pr': + return 'github'; + case 'gitlab-issue': + case 'gitlab-pr': + return 'gitlab'; + case 'linear-issue': + return 'linear'; + case 'jira-issue': + return 'jira'; + case 'incidentio-follow-up': + return 'incidentio'; + default: + return undefined; + } +} + +function metadataString(metadata: Record, key: string): string | undefined { + const value = metadata[key]; + return typeof value === 'string' && value.trim() ? value.trim() : undefined; +} + +function metadataStrings(metadata: Record, key: string): string[] { + const value = metadata[key]; + if (!Array.isArray(value)) return []; + return value.flatMap(entry => (typeof entry === 'string' && entry.trim() ? [entry.trim()] : [])); +} + +function creator(provider: ProviderPersonSource, metadata: Record): string | undefined { + if (provider === 'github' || provider === 'gitlab') return metadataString(metadata, 'author'); + return ( + metadataString(metadata, 'creator') ?? + metadataString(metadata, 'linearCreator') ?? + metadataString(metadata, 'author') + ); +} + +function assignees(provider: ProviderPersonSource, metadata: Record): string[] { + if (provider === 'github' || provider === 'gitlab') { + const assignee = metadataString(metadata, 'assignee'); + return [...new Set([...metadataStrings(metadata, 'assignees'), ...(assignee ? [assignee] : [])])]; + } + const assignee = metadataString(metadata, 'assignee') ?? metadataString(metadata, 'linearAssignee'); + return assignee ? [assignee] : []; +} + +/** Only a pull request has reviewers asked of it. */ +function requestedReviewers(item: SourceFacts): string[] { + if (item.source !== 'github-pr' && item.source !== 'gitlab-pr') return []; + return metadataStrings(item.metadata, 'requestedReviewers'); +} + +/** The people the item's source names, by what they are to it. None for an item no provider filed. */ +export function providerPeople(item: SourceFacts): Record { + const source = personSource(item.source); + if (!source) return { authored: [], assigned: [], 'review-requested': [] }; + const person = (name: string): ProviderPerson => ({ id: `${source}:${name.toLowerCase()}`, name, source }); + const author = creator(source, item.metadata); + return { + authored: author ? [person(author)] : [], + assigned: assignees(source, item.metadata).map(person), + 'review-requested': requestedReviewers(item).map(person), + }; +} + +/** Each person filter must match (AND); within one, any picked person in any of its roles will do (OR). */ +export function matchesPeople(relations: BoardRelations, picked: BoardPeopleFilters): boolean { + return BOARD_PERSON_FIELDS.every(field => { + const ids = picked[field]; + if (ids.size === 0) return true; + return PERSON_FIELD_ROLES[field].some(role => { + for (const id of ids) { + if (relations[role].has(id)) return true; + } + return false; + }); + }); +} diff --git a/mastracode/factory/src/work-items/card-search-text.ts b/mastracode/factory/src/work-items/card-search-text.ts new file mode 100644 index 00000000000..8e4e61dc7d5 --- /dev/null +++ b/mastracode/factory/src/work-items/card-search-text.ts @@ -0,0 +1,11 @@ +import type { Card } from '../storage/domains/work-items/base.js'; +import { workItemNumber } from './card-number.js'; + +/** What a search reads of a card, lowercased: its title, its key (`ENG-42`), its number and its source id. */ +export function cardSearchText(card: Card): string { + const number = workItemNumber(card); + // `#12` also answers a search for `12`. + return [card.title, card.workItem.key, number === null ? null : `#${number}`, card.externalSource?.externalId] + .join(' ') + .toLowerCase(); +} diff --git a/mastracode/factory/src/work-items/card-source-filters.test.ts b/mastracode/factory/src/work-items/card-source-filters.test.ts new file mode 100644 index 00000000000..6821c0af992 --- /dev/null +++ b/mastracode/factory/src/work-items/card-source-filters.test.ts @@ -0,0 +1,91 @@ +import { describe, expect, it } from 'vitest'; + +import { hasEveryLabel, metadataLabels } from './card-labels.js'; +import { boardSource, matchesSourceFilters, PULL_REQUEST_SOURCE_FILTER } from './card-source-filters.js'; +import type { SourceFacts } from './card-source-filters.js'; + +function filters(source: string[] = [], linearProject: string[] = []) { + return { source: new Set(source), linearProject: new Set(linearProject) }; +} + +function card(source: SourceFacts['source'], more: { linearProjectId?: string; hasPullRequest?: boolean } = {}) { + return { + source, + metadata: more.linearProjectId === undefined ? {} : { linearProjectId: more.linearProjectId }, + hasPullRequest: more.hasPullRequest ?? false, + }; +} + +describe('boardSource', () => { + it.each([ + ['github-issue', 'github'], + ['github-pr', 'github'], + ['gitlab-pr', 'gitlab'], + ['linear-issue', 'linear'], + ['jira-issue', 'jira'], + ['incidentio-follow-up', 'incidentio'], + ['slack-thread', 'slack'], + ['manual', 'manual'], + ] as const)('files a %s card under %s', (source, filedUnder) => { + expect(boardSource(source)).toBe(filedUnder); + }); +}); + +describe('matchesSourceFilters', () => { + it('keeps every card when nothing is picked', () => { + expect(matchesSourceFilters(card('manual'), filters())).toBe(true); + expect(matchesSourceFilters(card('linear-issue'), filters())).toBe(true); + }); + + it('keeps the cards of any picked source', () => { + const picked = filters(['github', 'manual']); + + expect(matchesSourceFilters(card('github-pr'), picked)).toBe(true); + expect(matchesSourceFilters(card('manual'), picked)).toBe(true); + expect(matchesSourceFilters(card('linear-issue'), picked)).toBe(false); + // A Slack thread is not a card filed by hand. + expect(matchesSourceFilters(card('slack-thread'), picked)).toBe(false); + }); + + it('keeps every card that has a pull request when pull requests are picked, whatever filed it', () => { + const picked = filters([PULL_REQUEST_SOURCE_FILTER]); + + expect(matchesSourceFilters(card('linear-issue', { hasPullRequest: true }), picked)).toBe(true); + expect(matchesSourceFilters(card('manual', { hasPullRequest: true }), picked)).toBe(true); + expect(matchesSourceFilters(card('github-issue'), picked)).toBe(false); + }); + + it('keeps only the Linear cards of a project picked alone', () => { + const picked = filters([], ['project-a']); + + expect(matchesSourceFilters(card('linear-issue', { linearProjectId: 'project-a' }), picked)).toBe(true); + expect(matchesSourceFilters(card('linear-issue', { linearProjectId: 'project-b' }), picked)).toBe(false); + expect(matchesSourceFilters(card('linear-issue'), picked)).toBe(false); + expect(matchesSourceFilters(card('github-issue'), picked)).toBe(false); + }); + + it('narrows only the Linear cards when a project is picked beside other sources', () => { + const picked = filters(['github', 'linear'], ['project-a']); + + expect(matchesSourceFilters(card('github-issue'), picked)).toBe(true); + expect(matchesSourceFilters(card('linear-issue', { linearProjectId: 'project-a' }), picked)).toBe(true); + expect(matchesSourceFilters(card('linear-issue', { linearProjectId: 'project-b' }), picked)).toBe(false); + }); +}); + +describe('card labels', () => { + it('reads the text labels a source put on an item', () => { + expect(metadataLabels({ labels: ['bug', 7, null, 'Memory'] })).toEqual(['bug', 'Memory']); + expect(metadataLabels({ labels: 'bug' })).toEqual([]); + expect(metadataLabels({})).toEqual([]); + }); + + it('needs every picked label on the item', () => { + const labels = new Set(['bug', 'Memory']); + + expect(hasEveryLabel(labels, [])).toBe(true); + expect(hasEveryLabel(labels, ['bug', 'Memory'])).toBe(true); + expect(hasEveryLabel(labels, ['bug', 'docs'])).toBe(false); + expect(hasEveryLabel(labels, ['memory'])).toBe(false); + }); +}); diff --git a/mastracode/factory/src/work-items/card-source-filters.ts b/mastracode/factory/src/work-items/card-source-filters.ts new file mode 100644 index 00000000000..dabbb1cf5d6 --- /dev/null +++ b/mastracode/factory/src/work-items/card-source-filters.ts @@ -0,0 +1,46 @@ +import type { WorkItemBranchSource } from '../work-item-branch.js'; + +/** What a board filter reads of a card or of an issue not filed yet: where it came from and what that source says of it. */ +export interface SourceFacts { + source: WorkItemBranchSource; + /** What the source says of the item: its labels, people, Linear project. */ + metadata: Record; +} + +/** The source filters a board view picked. An empty set picks everything. */ +export interface SourceFilters { + source: ReadonlySet; + linearProject: ReadonlySet; +} + +/** Picks every card that has a pull request, whatever it was filed from. */ +export const PULL_REQUEST_SOURCE_FILTER = 'pull-request'; + +const LINEAR_ONLY: ReadonlySet = new Set(['linear']); + +/** The source a card is filtered under: its provider, whether it tracks an issue or a pull request. */ +export function boardSource(source: WorkItemBranchSource): string { + if (source === 'incidentio-follow-up') return 'incidentio'; + return source.split('-')[0] ?? source; +} + +/** The sources a view keeps; empty keeps all. A Linear project picked alone keeps Linear. */ +export function pickedBoardSources(filters: SourceFilters): ReadonlySet { + if (filters.source.size > 0 || filters.linearProject.size === 0) return filters.source; + return LINEAR_ONLY; +} + +/** Whether the view's source and Linear project filters keep the item. */ +export function matchesSourceFilters(item: SourceFacts & { hasPullRequest: boolean }, filters: SourceFilters): boolean { + const sources = pickedBoardSources(filters); + if ( + sources.size > 0 && + !sources.has(boardSource(item.source)) && + !(sources.has(PULL_REQUEST_SOURCE_FILTER) && item.hasPullRequest) + ) { + return false; + } + if (item.source !== 'linear-issue' || filters.linearProject.size === 0) return true; + const projectId = item.metadata.linearProjectId; + return typeof projectId === 'string' && filters.linearProject.has(projectId); +} diff --git a/mastracode/factory/src/work-items/create-work-item.ts b/mastracode/factory/src/work-items/create-work-item.ts index 6fce843b665..c0f060c2de5 100644 --- a/mastracode/factory/src/work-items/create-work-item.ts +++ b/mastracode/factory/src/work-items/create-work-item.ts @@ -13,6 +13,7 @@ import type { FactoryTransitionRequest, FactoryTransitionService } from '../rule import type { EmitAuditInput } from '../storage/domains/audit/domain.js'; import { WorkItemUpdateConflictError } from '../storage/domains/work-items/base.js'; import type { CreateWorkItemInput, Card, WorkItemsStorage } from '../storage/domains/work-items/base.js'; +import { CARD_NUMBER_METADATA_KEY } from './card-number.js'; /** Records one audit event for the caller; routes bind it to the request, tools to the session's person. */ export type FactoryAuditEmit = (input: EmitAuditInput) => Promise; @@ -22,13 +23,6 @@ type TransitionResult = Awaited { let highest = 0; diff --git a/mastracode/factory/src/work-items/list-related-cards.ts b/mastracode/factory/src/work-items/list-related-cards.ts new file mode 100644 index 00000000000..2a49cb3c9d8 --- /dev/null +++ b/mastracode/factory/src/work-items/list-related-cards.ts @@ -0,0 +1,26 @@ +import { isPullRequestCard } from '../boards/semantics.js'; +import type { Card } from '../storage/domains/work-items/base.js'; +import { workItemBranchSource } from '../work-item-branch.js'; +import { relatedCardIndex } from './related-cards.js'; +import type { PullRequestFacts } from './related-cards.js'; + +const CARD_PULL_REQUESTS: PullRequestFacts = { + isPullRequest: card => isPullRequestCard({ source: workItemBranchSource(card.externalSource) }), + headBranch: card => { + const branch = card.workItem.metadata?.headBranch; + return typeof branch === 'string' ? branch : undefined; + }, +}; + +// One index per list version: `listShared` returns the same array until a card changes. +const relatedByList = new WeakMap Card[]>(); + +/** Reads the cards related to one of the list's cards, in list order. */ +export function relatedCardsIn(list: readonly Card[]): (card: Card) => Card[] { + let relatedTo = relatedByList.get(list); + if (!relatedTo) { + relatedTo = relatedCardIndex(list, CARD_PULL_REQUESTS); + relatedByList.set(list, relatedTo); + } + return relatedTo; +} diff --git a/mastracode/factory/src/work-items/search-words.ts b/mastracode/factory/src/work-items/search-words.ts new file mode 100644 index 00000000000..53e42c8984d --- /dev/null +++ b/mastracode/factory/src/work-items/search-words.ts @@ -0,0 +1,9 @@ +/** The words of a typed search, lowercased. */ +export function searchWords(query: string): string[] { + return query.toLowerCase().split(/\s+/).filter(Boolean); +} + +/** Whether every word is somewhere in `text`, which the caller has lowercased. */ +export function hasEveryWord(text: string, words: readonly string[]): boolean { + return words.every(word => text.includes(word)); +} diff --git a/packages/cli/src/commands/api/descriptors.test.ts b/packages/cli/src/commands/api/descriptors.test.ts index 76d46e21e7b..a5395770fd2 100644 --- a/packages/cli/src/commands/api/descriptors.test.ts +++ b/packages/cli/src/commands/api/descriptors.test.ts @@ -132,6 +132,7 @@ describe('api command descriptors', () => { 'factoryWork-itemList': ['workItemList', ['id'], true, false, false], 'factoryWork-itemStarters': ['workItemStarters', ['id'], false, false, false], 'factoryWork-itemActivity': ['workItemActivity', ['id'], true, true, false], + 'factoryWork-itemFilter-options': ['workItemFilterOptions', ['id'], false, false, false], 'factoryWork-itemCreate': ['workItemCreate', ['id'], true, true, false], 'factoryWork-itemUpdate': ['workItemUpdate', ['id'], true, true, false], 'factoryWork-itemDelete': ['workItemDelete', ['id'], false, false, false], @@ -140,6 +141,7 @@ describe('api command descriptors', () => { 'factoryWork-itemAutomation-run': ['workItemAutomationRun', ['id', 'workItemId'], true, true, false], factoryBoards: ['boardCatalog', ['id'], false, false, false], factoryBoardGet: ['boardGet', ['id', 'boardKey'], false, false, false], + factoryBoardPhases: ['boardPhases', ['id', 'boardKey'], true, false, false], factoryBoardCreate: ['boardCreate', ['id'], true, true, false], factoryBoardUpdate: ['boardReplace', ['id', 'boardKey'], true, true, false], factoryBoardDelete: ['boardDelete', ['id', 'boardKey'], true, true, false], diff --git a/packages/cli/src/commands/api/factory-route-metadata.generated.ts b/packages/cli/src/commands/api/factory-route-metadata.generated.ts index 85ca8517e02..ab350c196e8 100644 --- a/packages/cli/src/commands/api/factory-route-metadata.generated.ts +++ b/packages/cli/src/commands/api/factory-route-metadata.generated.ts @@ -192,6 +192,38 @@ export const FACTORY_API_ROUTE_METADATA = { "kind": "single" } }, + "GET /web/factory/projects/:id/boards/:boardKey/phases": { + "contractKey": "boardPhases", + "method": "GET", + "path": "/web/factory/projects/:id/boards/:boardKey/phases", + "description": "List the cards under each phase of a board view, in order, with how many match", + "pathParams": [ + "id", + "boardKey" + ], + "queryParams": [ + "assignee", + "author", + "cards", + "item", + "label", + "limit", + "linearProject", + "q", + "reviewer", + "sort", + "source", + "teammate", + "window", + "worked" + ], + "bodyParams": [], + "hasQuery": true, + "hasBody": false, + "responseShape": { + "kind": "single" + } + }, "GET /web/factory/projects/:id/decisions": { "contractKey": "decisionList", "method": "GET", @@ -393,6 +425,22 @@ export const FACTORY_API_ROUTE_METADATA = { "kind": "single" } }, + "GET /web/factory/projects/:id/work-items/filter-options": { + "contractKey": "workItemFilterOptions", + "method": "GET", + "path": "/web/factory/projects/:id/work-items/filter-options", + "description": "List the labels and people the cards of a project can be filtered by", + "pathParams": [ + "id" + ], + "queryParams": [], + "bodyParams": [], + "hasQuery": false, + "hasBody": false, + "responseShape": { + "kind": "single" + } + }, "GET /web/factory/projects/:id/work-items/starters": { "contractKey": "workItemStarters", "method": "GET", @@ -2214,6 +2262,307 @@ export const FACTORY_API_ROUTE_SCHEMAS = { } } }, + "GET /web/factory/projects/:id/boards/:boardKey/phases": { + "path": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" + }, + "boardKey": { + "type": "string", + "minLength": 1, + "maxLength": 128 + } + }, + "required": [ + "id", + "boardKey" + ] + }, + "query": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "sort": { + "default": "recent", + "type": "string", + "enum": [ + "recent", + "recent-mine", + "created-newest", + "created-oldest" + ] + }, + "q": { + "type": "string", + "maxLength": 200 + }, + "source": { + "$ref": "#/$defs/__schema0" + }, + "linearProject": { + "$ref": "#/$defs/__schema0" + }, + "label": { + "$ref": "#/$defs/__schema0" + }, + "teammate": { + "$ref": "#/$defs/__schema0" + }, + "author": { + "$ref": "#/$defs/__schema0" + }, + "assignee": { + "$ref": "#/$defs/__schema0" + }, + "reviewer": { + "$ref": "#/$defs/__schema0" + }, + "worked": { + "$ref": "#/$defs/__schema0" + }, + "limit": { + "type": "string" + }, + "window": { + "$ref": "#/$defs/__schema2" + }, + "item": { + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" + }, + "cards": { + "type": "string", + "enum": [ + "true" + ] + } + }, + "$defs": { + "__schema0": { + "default": [], + "maxItems": 100, + "type": "array", + "items": { + "$ref": "#/$defs/__schema1" + } + }, + "__schema1": { + "type": "string", + "minLength": 1, + "maxLength": 512 + }, + "__schema2": { + "maxItems": 64, + "type": "array", + "items": { + "$ref": "#/$defs/__schema3" + } + }, + "__schema3": { + "type": "string" + } + } + }, + "response": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "phases": { + "type": "array", + "items": { + "type": "object", + "properties": { + "phase": { + "type": "string" + }, + "total": { + "$ref": "#/$defs/__schema0" + }, + "cards": { + "type": "array", + "items": { + "$ref": "#/$defs/__schema1" + } + } + }, + "required": [ + "phase", + "total", + "cards" + ] + } + }, + "item": { + "type": "object", + "properties": { + "id": { + "$ref": "#/$defs/__schema2" + }, + "version": { + "$ref": "#/$defs/__schema3" + }, + "places": { + "type": "array", + "items": { + "type": "object", + "properties": { + "phase": { + "type": "string" + }, + "position": { + "$ref": "#/$defs/__schema0" + } + }, + "required": [ + "phase", + "position" + ] + } + } + }, + "required": [ + "id", + "version", + "places" + ] + }, + "related": { + "type": "array", + "items": { + "$ref": "#/$defs/__schema1" + } + }, + "relatedTotal": { + "$ref": "#/$defs/__schema0" + }, + "boardTotal": { + "$ref": "#/$defs/__schema0" + }, + "matchingTotal": { + "$ref": "#/$defs/__schema0" + }, + "workItems": { + "type": "array", + "items": { + "type": "object", + "properties": { + "workItem": { + "type": "object", + "properties": { + "provider": { + "type": "string" + }, + "key": { + "type": [ + "string", + "null" + ] + }, + "url": { + "type": [ + "string", + "null" + ] + }, + "title": { + "type": "string" + }, + "state": { + "type": [ + "string", + "null" + ] + }, + "labels": { + "type": "array", + "items": { + "type": "string" + } + }, + "author": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "provider", + "key", + "url", + "title", + "state", + "labels", + "author" + ], + "additionalProperties": {} + }, + "version": { + "type": "string" + } + }, + "required": [ + "version" + ], + "additionalProperties": {} + } + }, + "runningSessionIds": { + "type": "array", + "items": { + "type": "string" + } + }, + "parkedSessionIds": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "phases", + "related", + "relatedTotal", + "boardTotal", + "matchingTotal", + "runningSessionIds", + "parkedSessionIds" + ], + "$defs": { + "__schema0": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "__schema1": { + "type": "object", + "properties": { + "id": { + "$ref": "#/$defs/__schema2" + }, + "version": { + "$ref": "#/$defs/__schema3" + } + }, + "required": [ + "id", + "version" + ] + }, + "__schema2": { + "type": "string" + }, + "__schema3": { + "type": "string" + } + } + } + }, "GET /web/factory/projects/:id/decisions": { "path": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -3705,6 +4054,73 @@ export const FACTORY_API_ROUTE_SCHEMAS = { ] } }, + "GET /web/factory/projects/:id/work-items/filter-options": { + "path": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" + } + }, + "required": [ + "id" + ] + }, + "response": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "labels": { + "type": "array", + "items": { + "type": "string" + } + }, + "people": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "source": { + "type": "string", + "enum": [ + "github", + "gitlab", + "linear", + "jira", + "incidentio" + ] + } + }, + "required": [ + "id", + "name", + "source" + ] + } + }, + "actorIds": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "labels", + "people", + "actorIds" + ] + } + }, "GET /web/factory/projects/:id/work-items/starters": { "path": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -9339,6 +9755,7 @@ export const FACTORY_API_ROUTE_CATALOG = { "attentionList": "GET /web/factory/projects/:id/attention", "boardCatalog": "GET /web/factory/projects/:id/boards", "boardGet": "GET /web/factory/projects/:id/boards/:boardKey", + "boardPhases": "GET /web/factory/projects/:id/boards/:boardKey/phases", "decisionList": "GET /web/factory/projects/:id/decisions", "projectEnvironmentGet": "GET /web/factory/projects/:id/environment", "projectEnvironmentBuilds": "GET /web/factory/projects/:id/environment/builds", @@ -9350,6 +9767,7 @@ export const FACTORY_API_ROUTE_CATALOG = { "projectSandboxEnvsList": "GET /web/factory/projects/:id/sandbox-envs", "workItemList": "GET /web/factory/projects/:id/work-items", "workItemActivity": "GET /web/factory/projects/:id/work-items/activity", + "workItemFilterOptions": "GET /web/factory/projects/:id/work-items/filter-options", "workItemStarters": "GET /web/factory/projects/:id/work-items/starters", "skillList": "GET /web/factory/skills", "projectUpdate": "PATCH /web/factory/projects/:id", diff --git a/packages/cli/src/commands/api/index.ts b/packages/cli/src/commands/api/index.ts index e0f1e0b5595..63f3b291154 100644 --- a/packages/cli/src/commands/api/index.ts +++ b/packages/cli/src/commands/api/index.ts @@ -711,6 +711,10 @@ export function registerApiCommand(program: CommanderCommand): void { }, ], }); + addAction(factoryWorkItem, 'filter-options', FACTORY_API_ROUTE_CATALOG.workItemFilterOptions, { + description: 'List the labels and people a Factory board can be filtered by', + routePlacement: 'origin', + }); addAction(factoryWorkItem, 'create', FACTORY_API_ROUTE_CATALOG.workItemCreate, { description: 'Create a Factory work item in Intake', input: 'required', @@ -771,6 +775,17 @@ export function registerApiCommand(program: CommanderCommand): void { description: "Get a board's definition and, except for the legacy Review board, its revision", routePlacement: 'origin', }); + addAction(factoryBoard, 'phases', FACTORY_API_ROUTE_CATALOG.boardPhases, { + description: 'List the first cards under each phase of a Factory board, with how many each phase holds', + input: 'optional', + routePlacement: 'origin', + examples: [ + { + description: 'The ten latest bugs under each phase of the Work board, with the card bodies', + command: `mastra api factory board phases work '{"label":["bug"],"limit":10,"cards":"true"}'`, + }, + ], + }); addAction(factoryBoard, 'create', FACTORY_API_ROUTE_CATALOG.boardCreate, { description: 'Create a board on a Factory project', input: 'required', From f75eb1a197d7b66bfcb9dee1db06be7bfde55dde Mon Sep 17 00:00:00 2001 From: Damien Schneider <74979845+damien-schneider@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:33:11 -0800 Subject: [PATCH 004/239] feat(factory-ui): load the board by phase, searched and filtered on the server (#30191) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **─────── TLDR ───────** > The Factory board now loads the first 50 cards of each column and more as you scroll, and searches, filters and sorts on the server, instead of downloading every card of the project. The board page was the last screen that read the whole project: every card with its description, on open and again on each change, to draw a few dozen cards per column. It now asks the two reads of #30177 for what it shows, keeps each card by id, and downloads a card only when the version the server names differs from the one it holds. Stacked on #30177. ### Behavior changed opening a board   ├─ **was** — one read of every card of the project   └─ **now** — one read: each column's count and its first 50 cards reaching the end of a column   ├─ **was** — every card was already in the browser   └─ **now** — the column lists twice as deep; only the cards not held are downloaded. Ends that come into view together are listed in one read, and each column waits for its own a change on the board (feed frame)   ├─ **was** — the whole board again, or its `since` delta   └─ **now** — the ids and versions of the listed cards, then only the cards whose version differs. A version is a hash of the card's body, so two writes in one millisecond, or a card the server presents differently with no write, are downloaded too typing in "Search cards"   ├─ **was** — the exact phrase, in the browser, at each key   └─ **now** — on the server, 150 ms after the last key: every word in any order, a card number or a source id filters and sort   ├─ **was** — in the browser; a candidate's live labels and people overrode the stored card   └─ **now** — on the server, from the stored card; "worked on" is its creator, movers and session starters a linked card (`?item=`) or the card held open   └─ **now** — the server answers its body and the phases holding it, apart from the listing. The page shows it on top of each of those phases until scrolling lists it in place, so it stays through a refresh, a search or another sort, and the cards above it are not downloaded. The linked card is read from the address at each render, so leaving the link stops asking for it a "load more" read that fails   └─ **new** — the board's error notice replaces the page, as for any failed board read; it offers Retry the sidebar's session list on a board page   ├─ **was** — borrowed the board's whole-project read   └─ **now** — reads the cards holding a session, as on every other page candidates in the first column (issues and pull requests without a card)   ├─ **was** — shown as soon as their feed answered, minus those the loaded board already held   └─ **now** — shown once the server says which are already filed, one read per 50 feed items, for the sources on show only; a lookup that fails shows the feed's error with Retry Drag and drop, card details, saved views and the command palette behave as before. ### Shape changed | | | | |---|---|---| | **+** | `useBoardPhasesQuery(project, request, openCard?)` | the one read the board page makes | | **+** | `boardPhasesRequest` · `shownBoardPhases` | the view as the server is asked for it, and its answer as the page draws it | | **+** | `e2e/ui/board-reads.ts` | UI suites answer both reads with the server's own modules, from the cards a test stubs | | **−** | `useWorkItemsQuery` · `readBoard` · the `since` merge | no caller reads the whole project | | **−** | `boardOrder.ts` · `pageLoadsBoard.ts` · `useParkedSessions` | ordering and parked sessions come with the phases read | - `mastracode/factory-ui/src/hooks/` - └─ `useWorkItems.ts` — phases read, cards by id, optimistic patches over every snapshot - `mastracode/factory-ui/src/ui/domains/factory/` - └─ `boardPhases.ts` · `boardPhasesRequest.ts` — new - └─ `boardFilters.ts` · `boardPeople.ts` · `boardLabels.ts` · `boardSourceFilters.ts` — the server's rules, imported - └─ `hooks/useBoardItems.ts` · `useBoardView.ts` · `useBoardRuns.ts` · `useBoardIntake.ts` - `mastracode/factory-ui/src/ui/pages/board/` - └─ `BoardContent.tsx` · `BoardStages.tsx` — windows per phase, linked card, open card ### Decisions - **cards by id, compared by version** — a refresh names cards and the browser fetches what differs, so an unchanged card is never downloaded twice. A card written here keeps the version it had until the next read, which downloads it once. - **"phase" for the read, "column" for the layout** — the request, the keys and the snapshot follow the server's `phases`. The board still draws columns, and a list draws groups. - **the linked card sits on top of its phase** — not at its place in the order, which would need the cards above it. Scrolling the phase that deep puts it in place. - **the open card rides on the reads the page makes anyway** — opening or closing a card the view lists sends nothing. A view read without it is read once more for that card, so it stays open through a change of order; the server still decides which phase holds it. - **tests run the server's rules** — the UI suites compute phases with `boardPhases` itself, so a rule changed on the server fails here instead of drifting. ### Gain Requests the page sends for the cards of a 250-card column, counted in the UI suite: | action | before | now | |---|---|---| | open the board | 1, every card | 1, 50 cards and the counts | | refresh, nothing shown changed | 1, every card or the delta | 1, ids and versions only | | refresh, one card changed | 1, every card or the delta | 2: ids and versions, then that card | | load more | 0 | 2: ids and versions, then the 50 new cards | | search a word | 0 | 2: ids and versions, then the matches not held | A link to the last card of a 2,000-card column, same suite: 51 cards downloaded in one read, the first 50 and the linked one. The first version of this PR downloaded all 2,000. Bytes per read are in #30177: 414 KB gzipped for a first open at 10,000 cards against 11.4 MB for the whole board, and 9 KB for each later read. Those were measured with time stamps; a version is longer, and 300 names weigh 7.8 KB gzipped against 3.3 KB. In Chromium, on a 610-card board with two columns of about 300 (stubbed server answering with the server's own rules, cards without descriptions): opening sends 3 reads and 111 KB of card JSON for 112 cards, against 548 KB for the whole board. Scrolling both columns to their end sends one listing (18 KB) and the 100 new cards (90 KB). Each refresh after that sends the ids and stamps again (18 KB at that depth) and no card. These Chromium figures date from before the cards were named by version and were not measured again. ### Watch - **deploy order** — the page has no fallback: it needs a server with the phases read of #30177. - **a linked card past what its column lists** — it shows first in the column, out of the sort order, until the column is scrolled down to it. - **a card held open** — it takes the place of the linked card in the read, so the linked card can leave a refreshed column until the open one closes. - **a card moved under "created" sorts** — it can land below the cards its new column lists; the count shows it. - **search results** — a phrase that matched as a whole now matches cards holding each word anywhere. - **candidates wait for one more answer** — a feed page appears after its filed lookup, and the next page is offered only then. - **`board-virtualization.spec.ts`** — it had no stub for the feed the page opens, an unhandled request that failed all 23 tests; it stubs it now. Its draft test types in the description: the details dialog has no Comment box since #29062. ### Not verified - [ ] a signed-in browser on a real project — the local API answers 401 here - [ ] Postgres — the UI suites run the server's rules over stubbed cards - [ ] the browser's own 304 path — jsdom keeps no HTTP cache - [ ] `AppStartup.msw.test.tsx` (8 tests, `GET /web/status`) and `ThreadPageTeammateSession.msw.test.tsx` (1 test) fail the same way on the base branch. With that one request set aside, the 8 startup tests pass on the phases read - [ ] four thread page suites fail some tests in a full run and pass alone; none reads the board - [ ] the Playwright specs were not run again after the move to phases, versions and the new linked card; the two results below are from before it - [ ] `board-virtualization.spec.ts` — 20 of 24 pass. The 4 left fail the same way with the base branch's `src` under this spec: a collapsed list group still mounts its rows (3 — 75 to 91 cards mounted on the base, 40 to 56 here, under 40 expected), a jump to the end of a phone list lands short of it (1) - [ ] `board-list-row-layout.spec.ts` — 2 of 2 fail and are left as found: no feed stub, and its titles are hidden by the nested work item's title since #28961 --- > ████████████████████ **tests** `+1690 −818` — 64% of the additions > ███████████ **source** `+963 −671` > █ **changeset** `+7` **ELI5:** The Factory board used to load every project card at once. Now it loads a small first set of cards for each column and fetches more only when the user scrolls, so large projects load faster. ## Overview This change moves board paging, search, filtering, and sorting to the server. The board reads cards by phase. It fetches card bodies by ID and version. The change is based on `feat/factory-board-columns`. It changes 67 files, with 2660 lines added and 1489 removed. ## Server-backed board reads - The board requests phase counts and the first 50 cards for each phase. - Each phase loads more cards when its own sentinel is reached. Each phase tracks its own window and pagination. - Search, filters, and sort are sent in the phase request. - Card bodies are fetched by ID, up to 100 per request. Cached bodies are reused when their `version` matches the server. - `WorkItem.version` replaces `changedAt`. - `listWorkItems` requires an explicit filter. It no longer supports cursor reads or returns `removedIds`. - New request helpers: `boardPhasesRequest`, `deeperPhaseWindow` (doubles the listed count; minimum 50, maximum 999,999), and `isCardId`. - New fetch helpers: `fetchBoardPhases` and `fetchWorkItemFilterOptions`. ## Query and hook changes - `useWorkItems.ts` replaces the whole-board query with phase-view queries, a session-card query, filter-option queries, and filed-from queries. - Removed: `boardQueryOptions`, `useWorkItemsQuery`, and `useParkedSessions`. - Added: `useBoardPhasesQuery`, `useWorkItemFilterOptionsQuery`, `sessionCardsQueryOptions`, `boardPhasesQueryOptions`, `workItemFilterOptionsQueryOptions`, and `filedFromQueryOptions`. - `useSidebarWorkItemsQuery` no longer takes `boardOnPage`. - Transition mutations restore the item on error. They ignore results that are not newer than the cached revision. - Delete mutations remove the item from board and phase caches and update phase counts. - `queryKeys` gains entries for phases, phase views, filter options, and all-source filed-from keys. Source-filtered keys now nest the `sources` array. - `useBoardIntake` performs filed-card lookups itself, in batches of up to 50 candidates. Feeds wait for lookup results. Lookup failures appear as feed errors that can be retried. - `useBoardItems` requires `items` from the caller. Its `all`, `visible`, and refetch fields are removed. - `useBoardRuns` no longer takes `refetchItems`. It fetches the clicked card directly. - `useItemSessionStatuses` takes `parkedSessionIds` as an input. ## Client-side logic removed or moved - `boardOrder.ts` is deleted. `BOARD_SORTS` and `BoardSort` move to `boardSort.ts`. `BoardSort` now aliases `BoardPhasesSort`. - Removed from `boardItems.ts`: `metadataLabels` (moved to `@mastra/factory/work-items/card-labels`) and `cardMatchesSearch`. - Removed from `boardPeople.ts`: person-matching helpers and activity-based participant collection. `boardParticipants` now takes `people` from the server. - `boardLabels` now takes `labels` and `candidates`. Its item-matching helpers are removed. - `boardSourceFilters.ts` now uses shared source-filter code. Its matching helpers are removed. - Removed: `workItemHumanActorIds`, `belongsToBoard`, and `pageLoadsBoard`. - Removed from `boardCandidates.ts`: `stageContentCount`. Added: `candidateMatchesView`, which requires all people, label, source, and search-word filters to match. - New `boardPhases.ts` exports `shownBoardPhases`. It derives displayed cards and totals from a phase snapshot. - Removed from `BoardContent`: client-side filtering, ordering, and stage membership logic. ## Routing and prefetch - `prefetchBoard` builds a phase request from the URL. It skips the request when a saved-view parameter is present. - `prefetchSidebar` prefetches session cards. - New: `retiredReviewBoardSearch` and `prefetchRetiredReviewBoard`. Retired Review links keep only pull-request sources and redirect to the Work board. - If a board with ID `review` still exists, the redirect goes to that board. ## Types and public exports - Added to `api/types.ts`: `BoardPhasesResponse`, `WorkItemFilterOptions`, `BoardPhasesSort`, `BoardPhasesFilter`, and `BoardPhasesRequest`. - `BoardStages` takes an `openCard` prop. It no longer creates open-card state internally. - `BOARD_SEARCH_QUERY` is now exported from `useBoardView.ts`. ## Search and filter behavior - Search matches cards that contain all query words, in any order. Matching is case-insensitive. The summary of changes states that matching also covers card numbers and source IDs. - Filter-empty counts use server totals and candidate counts. ## Test changes - Test helpers and fixtures add `largeCardId`, `mockBoardRowLayout`, and `boardViewport`. - The MSW test helper adds `boardReadHandlers` for phase and filter-option reads. It also adds `isStubbedProjectRead` and `versionedCard`. - New tests cover phase reads, pagination, deep links, search, and refresh behavior. - Deleted: `boardOrder.test.ts`. - Several existing tests were changed to use the new hooks and fixtures. ## Verification status - The author reports that the Factory board loads and pages cards as described. - The author reports that drag and drop, card details, saved views, and the command palette behave as before. - Not verified by the author: a signed-in browser on a real project, Postgres, and the browser's 304 cache path. - Not rerun by the author after the latest changes: the Playwright specs. - Author-reported Playwright results: - `board-virtualization.spec.ts`: 20 of 24 tests pass. The author reports the four failures also occur on the base branch. - `board-list-row-layout.spec.ts`: 2 of 2 tests fail. The author attributes the failures to an unstubbed feed and to titles hidden by a nested work item. - Author-reported baseline failures: `AppStartup.msw.test.tsx` and `ThreadPageTeammateSession.msw.test.tsx`. With the noted request set excluded, the eight startup tests pass on the phase reads. - CI results: not available. ## Dependencies and risks - The page requires the phase reads from `#30177`. The author reports no fallback exists for servers without it. - The `.changeset/calm-phases-load.md` entry adds a patch release note for `mastra`. --------- Co-authored-by: Damien Schneider Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/calm-phases-load.md | 7 + .../e2e/board-virtualization.spec.ts | 59 ++- mastracode/factory-ui/e2e/ui/board-reads.ts | 278 ++++++++++++ mastracode/factory-ui/e2e/ui/msw-server.ts | 3 + mastracode/factory-ui/src/api/keys.ts | 25 +- mastracode/factory-ui/src/api/types.ts | 22 + .../hooks/__tests__/useWorkItems.msw.test.tsx | 421 ++++++++++++------ .../hooks/customBoardOperations.msw.test.tsx | 44 +- .../factory-ui/src/hooks/useWorkItems.ts | 394 ++++++++++++---- .../src/ui/__tests__/AppStartup.msw.test.tsx | 55 ++- .../BoardPagePagedReads.msw.test.tsx | 264 +++++++++++ .../BoardPagePendingStates.msw.test.tsx | 16 +- .../BoardPageReviewStates.msw.test.tsx | 4 +- .../BoardPageSavedViews.msw.test.tsx | 7 +- .../BoardPageSourceFilters.msw.test.tsx | 16 +- .../BoardPageWorkItemActivity.msw.test.tsx | 4 +- .../BoardVirtualization.msw.test.tsx | 61 +-- .../src/ui/__tests__/boardRowLayout.ts | 29 ++ .../__tests__/fixtures/boardSourceFilters.ts | 4 +- .../fixtures/hostedLinearProjectFilters.ts | 6 +- .../src/ui/__tests__/fixtures/largeBoard.ts | 7 +- .../domains/factory/boardCandidates.test.ts | 89 +++- .../src/ui/domains/factory/boardCandidates.ts | 51 ++- .../src/ui/domains/factory/boardFilters.ts | 3 +- .../src/ui/domains/factory/boardItems.ts | 15 - .../ui/domains/factory/boardLabels.test.ts | 67 +-- .../src/ui/domains/factory/boardLabels.ts | 34 +- .../src/ui/domains/factory/boardOrder.test.ts | 115 ----- .../src/ui/domains/factory/boardOrder.ts | 41 -- .../ui/domains/factory/boardPeople.test.ts | 301 ++----------- .../src/ui/domains/factory/boardPeople.ts | 222 +-------- .../ui/domains/factory/boardPhases.test.ts | 218 +++++++++ .../src/ui/domains/factory/boardPhases.ts | 72 +++ .../factory/boardPhasesRequest.test.ts | 61 +++ .../ui/domains/factory/boardPhasesRequest.ts | 58 +++ .../src/ui/domains/factory/boardSavedViews.ts | 3 +- .../src/ui/domains/factory/boardSort.ts | 12 +- .../factory/boardSourceFilters.test.ts | 32 -- .../ui/domains/factory/boardSourceFilters.ts | 43 +- .../src/ui/domains/factory/boardStages.ts | 4 - .../ui/domains/factory/cardPrimaryAction.ts | 3 +- .../factory/components/BoardCardParts.tsx | 2 +- .../components/BoardPropertiesMenu.tsx | 2 +- .../factory/components/boardFilterFields.tsx | 5 +- .../FeedEventsBoardRefresh.msw.test.tsx | 62 ++- .../__tests__/FeedEventsProvider.msw.test.tsx | 4 +- .../__tests__/useBoardIntake.msw.test.tsx | 231 +++++++++- .../domains/factory/hooks/useBoardIntake.ts | 114 ++++- .../ui/domains/factory/hooks/useBoardItems.ts | 33 +- .../ui/domains/factory/hooks/useBoardRuns.ts | 31 +- .../ui/domains/factory/hooks/useBoardView.ts | 4 +- .../factory/hooks/useFactoryActivity.ts | 5 +- .../factory/hooks/useItemSessionStatuses.ts | 6 +- .../src/ui/domains/factory/pageLoadsBoard.ts | 4 - .../factory/services/workItems.test.ts | 17 +- .../ui/domains/factory/services/workItems.ts | 107 +++-- .../ui/domains/factory/workItemActivity.ts | 9 - .../components/FactoryGlobalSearchContent.tsx | 2 +- .../GlobalSearchNavigationResults.tsx | 2 +- .../search/hooks/useGlobalSearchWorkItems.ts | 30 +- .../SessionsSectionSourceIcons.msw.test.tsx | 45 +- .../workspaces/hooks/useSessionListRows.ts | 3 +- .../__tests__/BoardPageFilters.msw.test.tsx | 2 +- .../src/ui/pages/board/BoardContent.tsx | 228 ++++++---- .../src/ui/pages/board/BoardStages.tsx | 5 +- mastracode/factory-ui/src/ui/routeLoaders.ts | 56 ++- mastracode/factory-ui/src/ui/router.tsx | 14 +- 67 files changed, 2682 insertions(+), 1511 deletions(-) create mode 100644 .changeset/calm-phases-load.md create mode 100644 mastracode/factory-ui/e2e/ui/board-reads.ts create mode 100644 mastracode/factory-ui/src/ui/__tests__/BoardPagePagedReads.msw.test.tsx create mode 100644 mastracode/factory-ui/src/ui/__tests__/boardRowLayout.ts delete mode 100644 mastracode/factory-ui/src/ui/domains/factory/boardOrder.test.ts delete mode 100644 mastracode/factory-ui/src/ui/domains/factory/boardOrder.ts create mode 100644 mastracode/factory-ui/src/ui/domains/factory/boardPhases.test.ts create mode 100644 mastracode/factory-ui/src/ui/domains/factory/boardPhases.ts create mode 100644 mastracode/factory-ui/src/ui/domains/factory/boardPhasesRequest.test.ts create mode 100644 mastracode/factory-ui/src/ui/domains/factory/boardPhasesRequest.ts delete mode 100644 mastracode/factory-ui/src/ui/domains/factory/pageLoadsBoard.ts diff --git a/.changeset/calm-phases-load.md b/.changeset/calm-phases-load.md new file mode 100644 index 00000000000..7db2330ca6b --- /dev/null +++ b/.changeset/calm-phases-load.md @@ -0,0 +1,7 @@ +--- +'mastra': patch +--- + +Improved the Factory board on large projects. The board now loads the first cards of each phase, then more as you scroll. It no longer downloads every card of the project. + +Search, filters and sorting now run on the server. Search matches cards that contain every word typed, in any order. It also finds a card by its number or source id. diff --git a/mastracode/factory-ui/e2e/board-virtualization.spec.ts b/mastracode/factory-ui/e2e/board-virtualization.spec.ts index 43b1c44032a..c269f291cee 100644 --- a/mastracode/factory-ui/e2e/board-virtualization.spec.ts +++ b/mastracode/factory-ui/e2e/board-virtualization.spec.ts @@ -1,7 +1,7 @@ import { expect, test } from '@playwright/test'; import { http, HttpResponse } from 'msw'; -import { largeBoard, largeCandidatePage } from '../src/ui/__tests__/fixtures/largeBoard'; +import { largeBoard, largeCandidatePage, largeCardId } from '../src/ui/__tests__/fixtures/largeBoard'; import { listedRepository } from './ui/factory-projects'; import { server } from './ui/msw-server'; @@ -44,6 +44,8 @@ test.describe('Factory board virtualization', () => { http.get('*/web/intake/bindings', () => HttpResponse.json({ bindings: [] })), http.get('*/web/linear/status', () => HttpResponse.json({ enabled: false, connected: false })), http.get('*/api/agent-controller/code/sessions/fp-1/permissions', () => HttpResponse.json({ permissions: [] })), + // The feed sends nothing here: the board is read once and scrolled. + http.get('*/web/factory/projects/fp-1/feed-events', () => new HttpResponse(null, { status: 404 })), ); await page.route( url => url.origin === baseURL && /^\/(web|auth|api)\//.test(url.pathname), @@ -86,7 +88,7 @@ test.describe('Factory board virtualization', () => { }), ), ); - await page.goto('/factories/fp-1/work?item=large-1'); + await page.goto(`/factories/fp-1/work?item=${largeCardId(1)}`); const halos = page.getByTestId('work-item-card').locator('.session-wick'); await expect(halos).toHaveCount(2); @@ -228,10 +230,15 @@ test.describe('Factory board virtualization', () => { const scroll = page .getByTestId('board-column-triage') .locator('xpath=ancestor::*[contains(concat(" ", normalize-space(@class), " "), " overflow-auto ")][1]'); - await scroll.evaluate(element => { - element.scrollTop = element.scrollHeight; - }); - await expect(page.getByRole('article', { name: 'Large task 0', exact: true })).toBeVisible(); + // The column lists itself deeper each time its end scrolls into view, down to its last card. + await expect(async () => { + await scroll.evaluate(element => { + element.scrollTop = element.scrollHeight; + }); + await expect(page.getByRole('article', { name: 'Large task 0', exact: true })).toBeVisible({ + timeout: 2_000, + }); + }).toPass({ timeout: 25_000 }); await expect(page.getByRole('article', { name: 'Large task 1999', exact: true })).toHaveCount(0); expect(await cards.count()).toBeLessThan(40); const bounds = await cards.evaluateAll(elements => @@ -291,7 +298,7 @@ test.describe('Factory board virtualization', () => { HttpResponse.json({ workItems: largeBoard(count) }), ), ); - await page.goto('/factories/fp-1/work?item=large-0'); + await page.goto(`/factories/fp-1/work?item=${largeCardId(0)}`); await expect(page.getByRole('article', { name: 'Large task 0', exact: true })).toBeInViewport(); await expect(page.getByRole('button', { name: 'Details for Large task 0', exact: true })).toBeFocused(); expect(await page.getByTestId('work-item-card').count()).toBeLessThan(40); @@ -300,6 +307,39 @@ test.describe('Factory board virtualization', () => { } } + test.describe('when the ends of two board columns scroll into view together', () => { + test.use(viewports[0].use); + test('lists both columns deeper', async ({ page }) => { + server.use( + http.get('*/web/factory/projects/fp-1/work-items', () => + HttpResponse.json({ + workItems: largeBoard(240).map((item, index) => ({ + ...item, + stages: [index < 120 ? 'triage' : 'planning'], + })), + }), + ), + ); + await page.goto('/factories/fp-1/work'); + await expect(page.getByRole('article', { name: 'Large task 119', exact: true })).toBeVisible(); + await page.getByRole('button', { name: 'New view', exact: true }).click(); + await page.getByRole('radio', { name: 'Board', exact: true }).click(); + await page.getByRole('button', { name: 'Save view', exact: true }).click(); + await expect(page.getByRole('group', { name: 'Board columns' })).toBeVisible(); + + await page + .getByTestId('board-column-triage') + .locator('xpath=ancestor::*[contains(concat(" ", normalize-space(@class), " "), " overflow-auto ")][1]') + .evaluate(element => { + element.scrollTop = element.scrollHeight; + }); + + // Each column listed its newest fifty: the fifty-first of each follows. + await expect(page.getByRole('article', { name: 'Large task 69', exact: true })).toBeVisible(); + await expect(page.getByRole('article', { name: 'Large task 189', exact: true })).toBeVisible(); + }); + }); + test.describe('when a card with open details is sorted out of the rendered range', () => { test.use(viewports[0].use); test('keeps the card mounted so its draft is there when the user scrolls back', async ({ page }) => { @@ -309,7 +349,8 @@ test.describe('Factory board virtualization', () => { .getByText('Large task 1999', { exact: true }) .click(); const details = page.getByRole('dialog', { name: 'Large task 1999' }); - await details.getByRole('textbox', { name: 'Comment' }).fill('Keep this draft'); + await details.getByRole('button', { name: 'Add a description', exact: true }).click(); + await details.getByRole('textbox', { name: 'Description', exact: true }).fill('Keep this draft'); await page.evaluate(() => { history.pushState(null, '', '?sort=created-oldest'); @@ -319,7 +360,7 @@ test.describe('Factory board virtualization', () => { expect(await page.getByTestId('work-item-card').count()).toBeLessThan(40); await page.getByRole('article', { name: 'Large task 1999', exact: true }).scrollIntoViewIfNeeded(); - await expect(details.getByRole('textbox', { name: 'Comment' })).toHaveValue('Keep this draft'); + await expect(details.getByRole('textbox', { name: 'Description', exact: true })).toHaveValue('Keep this draft'); }); }); }); diff --git a/mastracode/factory-ui/e2e/ui/board-reads.ts b/mastracode/factory-ui/e2e/ui/board-reads.ts new file mode 100644 index 00000000000..1e8ca4dda19 --- /dev/null +++ b/mastracode/factory-ui/e2e/ui/board-reads.ts @@ -0,0 +1,278 @@ +import type { Card } from '@mastra/factory'; +import { FACTORY_ROUTE_CONTRACTS } from '@mastra/factory/routes/contracts'; +import { workItemFilterOptions } from '@mastra/factory/work-items/board-filter-options'; +import { boardPhases } from '@mastra/factory/work-items/board-phases'; +import { http, HttpResponse } from 'msw'; +import { z } from 'zod'; + +/** + * The server's paged board reads for the UI suites, answered by the server's own rules from the + * project's cards as a test lists them. A test keeps stubbing one list of cards; the board asks + * for the phases of a board, and gets what the real server would answer for that list. + */ + +const dateSchema = z.coerce.date(); +const sourceRowSchema = z.custom( + value => typeof value === 'object' && value !== null, +); + +// What a test's card may leave out, with what the server's rules then read. +const wireCardSchema = z.object({ + id: z.string(), + workItemId: z.string().optional(), + parentBoardItemId: z.string().nullish(), + orgId: z.string().default('org-1'), + createdBy: z.string().default('user-1'), + factoryProjectId: z.string().default('fp-1'), + board: z.string().nullish(), + externalSource: z + .object({ + integrationId: z.string(), + type: z.string(), + workspaceId: z.string().optional(), + externalId: z.string(), + url: z + .string() + .nullish() + .transform(url => url ?? undefined), + }) + .nullish(), + parentWorkItemId: z.string().nullish(), + title: z.string().default(''), + description: z.string().nullish(), + stages: z.array(z.string()).default([]), + stageHistory: z + .array( + z.object({ + stage: z.string(), + enteredAt: z.string(), + exitedAt: z.string().optional(), + by: z.string().default('user-1'), + exitedBy: z.string().optional(), + }), + ) + .default([]), + sessions: z + .record( + z.string(), + z.object({ + sessionId: z.string(), + branch: z.string().default(''), + threadId: z.string().default(''), + startedBy: z.string().default('user-1'), + }), + ) + .default({}), + metadata: z.record(z.string(), z.unknown()).nullish(), + triageType: z.custom(value => value === null || typeof value === 'string').optional(), + acceptedAt: dateSchema.nullish(), + autonomyArmedAt: dateSchema.nullish(), + revision: z.number().default(1), + createdAt: dateSchema.default(new Date(0)), + updatedAt: dateSchema.optional(), + changedAt: dateSchema.nullish(), + workItem: z + .object({ + id: z.string().optional(), + provider: z.string().default('factory'), + externalId: z.string().nullish(), + key: z.string().nullish(), + url: z.string().nullish(), + title: z.string().optional(), + state: z.string().nullish(), + labels: z.array(z.string()).default([]), + author: z.string().nullish(), + metadata: z.record(z.string(), z.unknown()).nullish(), + sources: z.array(sourceRowSchema).default([]), + syncedAt: dateSchema.nullish(), + }) + .optional(), +}); + +/** The version of a card's body: it changes whenever anything of the card does. */ +function bodyVersion(wire: unknown): string { + let hash = 2166136261; + for (const char of JSON.stringify(wire)) hash = Math.imul(hash ^ (char.codePointAt(0) ?? 0), 16777619); + return (hash >>> 0).toString(16); +} + +/** A card a test lists on the wire, as the server sends it where it names cards by version. */ +export function versionedCard(wire: unknown): Record { + return { ...z.record(z.string(), z.unknown()).parse(wire), version: bodyVersion(wire) }; +} + +/** The card the server holds for a card a test lists on the wire. */ +function storedCard(wire: unknown): Card { + const card = wireCardSchema.parse(wire); + const updatedAt = card.updatedAt ?? card.createdAt; + const workItemId = card.workItemId ?? card.workItem?.id ?? card.id; + return { + id: card.id, + workItemId, + parentBoardItemId: card.parentBoardItemId ?? null, + orgId: card.orgId, + createdBy: card.createdBy, + factoryProjectId: card.factoryProjectId, + board: card.board ?? null, + externalSource: card.externalSource ?? null, + parentWorkItemId: card.parentWorkItemId ?? null, + title: card.workItem?.title ?? card.title, + description: card.description ?? null, + stages: card.stages, + stageHistory: card.stageHistory, + sessions: card.sessions, + metadata: card.metadata ?? null, + triageType: card.triageType ?? null, + acceptedAt: card.acceptedAt ?? null, + autonomyArmedAt: card.autonomyArmedAt ?? null, + revision: card.revision, + createdAt: card.createdAt, + updatedAt, + changedAt: card.changedAt ?? updatedAt, + workItem: { + id: workItemId, + orgId: card.orgId, + factoryProjectId: card.factoryProjectId, + provider: card.workItem?.provider ?? 'factory', + externalId: card.workItem?.externalId ?? card.externalSource?.externalId ?? card.id, + key: card.workItem?.key ?? null, + url: card.workItem?.url ?? null, + title: card.workItem?.title ?? card.title, + state: card.workItem?.state ?? null, + labels: card.workItem?.labels ?? [], + author: card.workItem?.author ?? null, + parentWorkItemId: card.parentWorkItemId ?? null, + metadata: card.workItem?.metadata ?? null, + sources: card.workItem?.sources ?? [], + revision: card.revision, + syncedAt: card.workItem?.syncedAt ?? null, + createdAt: card.createdAt, + updatedAt, + }, + }; +} + +/** A project as a test states it: its cards on the wire, its boards, and who reads it. */ +export interface StubbedProject { + workItems: readonly unknown[]; + boards: ReadonlyArray<{ id: string; phases: ReadonlyArray<{ id: string }> }>; + userId: string; + runningSessionIds?: readonly string[]; + parkedSessionIds?: readonly string[]; +} + +function queryValues(url: URL, name: string): string[] | undefined { + const values = url.searchParams.getAll(name); + return values.length > 0 ? values : undefined; +} + +/** The answer of the read of `boardKey`'s phases for `request`, as the server gives it for `project`. */ +export function answerBoardPhases(request: Request, project: StubbedProject, boardKey: string): Response { + const url = new URL(request.url); + const query = FACTORY_ROUTE_CONTRACTS.boardPhases.querySchema.safeParse({ + sort: url.searchParams.get('sort') ?? undefined, + q: url.searchParams.get('q') ?? undefined, + source: queryValues(url, 'source'), + linearProject: queryValues(url, 'linearProject'), + label: queryValues(url, 'label'), + teammate: queryValues(url, 'teammate'), + author: queryValues(url, 'author'), + assignee: queryValues(url, 'assignee'), + reviewer: queryValues(url, 'reviewer'), + worked: queryValues(url, 'worked'), + limit: url.searchParams.get('limit') ?? undefined, + window: queryValues(url, 'window'), + item: url.searchParams.get('item') ?? undefined, + cards: url.searchParams.get('cards') ?? undefined, + }); + if (!query.success) return HttpResponse.json({ error: 'invalid_phases_query' }, { status: 400 }); + const { cards: withBodies, ...view } = query.data; + const board = project.boards.find(candidate => candidate.id === boardKey); + if (!board) return HttpResponse.json({ error: 'board_not_found' }, { status: 404 }); + const phases = board.phases.map(phase => phase.id); + const wireById = new Map(); + const versions = new Map(); + const list = project.workItems.map(wire => { + const card = storedCard(wire); + versions.set(card.id, bodyVersion(wire)); + wireById.set(card.id, versionedCard(wire)); + return card; + }); + const { body, named } = boardPhases( + list, + { id: boardKey, phases }, + view, + project.userId, + card => versions.get(card.id) ?? '', + ); + const namedSessionIds = new Set( + named.flatMap(card => Object.values(card.sessions).map(session => session.sessionId)), + ); + return HttpResponse.json({ + ...body, + ...(withBodies ? { workItems: named.map(card => wireById.get(card.id)) } : {}), + runningSessionIds: (project.runningSessionIds ?? []).filter(id => namedSessionIds.has(id)), + parkedSessionIds: (project.parkedSessionIds ?? []).filter(id => namedSessionIds.has(id)), + }); +} + +/** The filter options read's answer, as the server gives it for the project's cards. */ +export function answerWorkItemFilterOptions(workItems: readonly unknown[]): Response { + return HttpResponse.json(workItemFilterOptions(workItems.map(storedCard))); +} + +const stubbedListSchema = z.object({ + workItems: z.array(z.unknown()).default([]), + runningSessionIds: z.array(z.string()).optional(), + parkedSessionIds: z.array(z.string()).optional(), +}); +const stubbedCatalogSchema = z.object({ + boards: z.array(z.object({ id: z.string(), phases: z.array(z.object({ id: z.string() })) })), +}); +const stubbedUserSchema = z.object({ user: z.object({ userId: z.string() }) }); + +const STUBBED_PROJECT_READ_HEADER = 'x-stubbed-project-read'; + +/** + * Whether `request` is one the ambient paged reads sent to learn what the test stubs, rather than + * one the app sent. A test that counts or records requests leaves these out. + */ +export function isStubbedProjectRead(request: Request): boolean { + return request.headers.has(STUBBED_PROJECT_READ_HEADER); +} + +/** + * The project as the running test stubs it: the cards its `work-items` handler lists, its board + * catalog and its signed-in user. An answer that is not one of these is the stub's own failure, + * which the paged read then fails with. + */ +async function stubbedProject(request: Request, factoryProjectId: string): Promise { + const { origin } = new URL(request.url); + const project = `${origin}/web/factory/projects/${encodeURIComponent(factoryProjectId)}`; + const read = { signal: request.signal, headers: { [STUBBED_PROJECT_READ_HEADER]: 'true' } }; + const [list, catalog, me] = await Promise.all([ + fetch(`${project}/work-items`, read), + fetch(`${project}/boards`, read), + fetch(`${origin}/auth/me`, read), + ]); + if (!list.ok) return list; + if (!catalog.ok) return catalog; + const user = me.ok ? stubbedUserSchema.safeParse(await me.json()) : undefined; + return { + ...stubbedListSchema.parse(await list.json()), + boards: stubbedCatalogSchema.parse(await catalog.json()).boards, + userId: user?.success ? user.data.user.userId : 'user-1', + }; +} + +/** Ambient paged board reads, answered from whatever list of cards the running test stubs. */ +export const boardReadHandlers = [ + http.get('*/web/factory/projects/:id/boards/:boardKey/phases', async ({ request, params }) => { + const project = await stubbedProject(request, String(params.id)); + return project instanceof Response ? project : answerBoardPhases(request, project, String(params.boardKey)); + }), + http.get('*/web/factory/projects/:id/work-items/filter-options', async ({ request, params }) => { + const project = await stubbedProject(request, String(params.id)); + return project instanceof Response ? project : answerWorkItemFilterOptions(project.workItems); + }), +]; diff --git a/mastracode/factory-ui/e2e/ui/msw-server.ts b/mastracode/factory-ui/e2e/ui/msw-server.ts index 49e925e4ac6..e38a34fdae2 100644 --- a/mastracode/factory-ui/e2e/ui/msw-server.ts +++ b/mastracode/factory-ui/e2e/ui/msw-server.ts @@ -2,6 +2,7 @@ import { http, HttpResponse } from 'msw'; import { setupServer } from 'msw/node'; import { builtinBoardCatalog } from './board-catalog'; +import { boardReadHandlers } from './board-reads'; /** * Shared MSW server for the jsdom web-ui test suite. The global setup @@ -61,7 +62,9 @@ export const server = setupServer( http.get('*/web/factory/projects/:id/sandbox-envs', () => HttpResponse.json({ envs: [], writable: true })), http.get('*/web/factory/projects/:id/audit', () => HttpResponse.json({ events: [], actors: {} })), http.get('*/web/factory/projects/:id/decisions', () => HttpResponse.json({ decisions: [] })), + // What a test stubs here is the project's cards: the board's paged reads are answered from it. http.get('*/web/factory/projects/:id/work-items', () => HttpResponse.json({ workItems: [] })), + ...boardReadHandlers, // Ambient empty board for the draft page's starters and activity; their tests override these with `server.use(...)`. http.get('*/web/factory/projects/:id/work-items/starters', () => HttpResponse.json({ diff --git a/mastracode/factory-ui/src/api/keys.ts b/mastracode/factory-ui/src/api/keys.ts index d0649349d13..37488d50167 100644 --- a/mastracode/factory-ui/src/api/keys.ts +++ b/mastracode/factory-ui/src/api/keys.ts @@ -1,4 +1,4 @@ -import type { WorkspaceChangesScope } from './types'; +import type { BoardPhasesRequest, WorkspaceChangesScope } from './types'; /** * Stable, scoped React Query keys for the settings API. @@ -25,6 +25,17 @@ export interface AvailableModelsFilter { threadId?: string; } +/** + * Whether a `boardPhasesView` key is of a view that searches and filters nothing: the one view + * every card of its board is in. + */ +export function isUnnarrowedBoardView(boardPhasesViewKey: readonly unknown[]): boolean { + const view = boardPhasesViewKey.at(-2); + if (typeof view !== 'object' || view === null || !('q' in view) || !('filters' in view)) return false; + const { q, filters } = view; + return q === '' && typeof filters === 'object' && filters !== null && Object.keys(filters).length === 0; +} + export const queryKeys = { serverFeatures: () => ['server-features'] as const, serverVersions: () => ['server-versions'] as const, @@ -111,14 +122,24 @@ export const queryKeys = { [...queryKeys.workItems(factoryProjectId), 'sessions'] as const, unstartedWorkItems: (factoryProjectId: string | undefined, search: string) => [...queryKeys.workItems(factoryProjectId), 'unstarted', search] as const, + workItemsFiledFromAny: (factoryProjectId: string | undefined) => + [...queryKeys.workItems(factoryProjectId), 'sources'] as const, workItemsFiledFrom: (factoryProjectId: string | undefined, sources: readonly string[]) => - [...queryKeys.workItems(factoryProjectId), 'sources', sources] as const, + [...queryKeys.workItemsFiledFromAny(factoryProjectId), sources] as const, + /** Every view of one board the tab holds. */ + boardPhases: (factoryProjectId: string | undefined, board: string) => + [...queryKeys.workItems(factoryProjectId), 'phases', board] as const, + /** One view of a board; `windows` is how deep each of its phases is listed. */ + boardPhasesView: (factoryProjectId: string | undefined, { board, windows, ...view }: BoardPhasesRequest) => + [...queryKeys.boardPhases(factoryProjectId, board), view, windows] as const, // Outside the board's key: these hold counts and dates, not cards, so a rewrite of the cached cards must not reach them. boardFacts: (factoryProjectId: string | undefined) => ['factory', 'board-facts', factoryProjectId ?? null] as const, workItemStarters: (factoryProjectId: string | undefined) => [...queryKeys.boardFacts(factoryProjectId), 'starters'] as const, workItemActivity: (factoryProjectId: string | undefined, depth: string) => [...queryKeys.boardFacts(factoryProjectId), 'activity', depth] as const, + workItemFilterOptions: (factoryProjectId: string | undefined) => + [...queryKeys.boardFacts(factoryProjectId), 'filter-options'] as const, knowledgeGraph: (factoryProjectId: string | undefined) => ['factory', 'knowledge-graph', factoryProjectId ?? null] as const, knowledgePage: (factoryProjectId: string | undefined, pageId: string | null, noteCursor?: string) => diff --git a/mastracode/factory-ui/src/api/types.ts b/mastracode/factory-ui/src/api/types.ts index 4710be6628e..873d3f4f431 100644 --- a/mastracode/factory-ui/src/api/types.ts +++ b/mastracode/factory-ui/src/api/types.ts @@ -28,6 +28,28 @@ export type CreateBoardBody = z.input; export type WorkItemActivity = z.infer; export type WorkItemListResponse = z.infer; +export type BoardPhasesResponse = z.infer; +export type WorkItemFilterOptions = z.infer; +type BoardPhasesQuery = z.output; +export type BoardPhasesSort = BoardPhasesQuery['sort']; +/** The filters of a board view: each is sent once per picked value. */ +export type BoardPhasesFilter = { + [Field in keyof BoardPhasesQuery]-?: BoardPhasesQuery[Field] extends Set ? Field : never; +}[keyof BoardPhasesQuery]; + +/** What the board read is asked: one view of a board, and how deep each of its phases is listed. */ +export interface BoardPhasesRequest { + board: string; + sort: BoardPhasesSort; + /** Empty searches nothing. */ + q: string; + /** The picked values of each filter, sorted. A filter that picks nothing is left out. */ + filters: Partial>; + /** How many cards a phase lists, for the phases listed deeper than the server's first page. */ + windows: Readonly>; + /** A card to answer for apart from the listing: its body, and where each phase holding it places it. */ + item?: string; +} import type { CustomProviderInfo, diff --git a/mastracode/factory-ui/src/hooks/__tests__/useWorkItems.msw.test.tsx b/mastracode/factory-ui/src/hooks/__tests__/useWorkItems.msw.test.tsx index f28528953d2..d8f3b5bd10a 100644 --- a/mastracode/factory-ui/src/hooks/__tests__/useWorkItems.msw.test.tsx +++ b/mastracode/factory-ui/src/hooks/__tests__/useWorkItems.msw.test.tsx @@ -1,26 +1,30 @@ -import { boardCheck } from '@mastra/factory/work-items/board-check'; -import { useMutation } from '@tanstack/react-query'; import type { QueryClient } from '@tanstack/react-query'; import { act, waitFor } from '@testing-library/react'; import { http, HttpResponse } from 'msw'; import { describe, expect, it } from 'vitest'; +import { answerBoardPhases, versionedCard } from '../../../e2e/ui/board-reads'; import { server } from '../../../e2e/ui/msw-server'; import { renderHookWithProviders, waitForMutationsIdle, TEST_BASE_URL } from '../../../e2e/ui/render'; import { queryKeys } from '../../api/keys'; +import type { BoardPhasesRequest } from '../../api/types'; import type { BoardSnapshot, WorkItem } from '../../ui/domains/factory/services/workItems'; import { + useBoardPhasesQuery, useDeleteWorkItemMutation, - useParkedSessions, useSessionWorkItemsQuery, + useSidebarWorkItemsQuery, useTransitionWorkItemMutation, useUpdateWorkItemMutation, useUpsertWorkItemMutation, - useWorkItemsQuery, } from '../useWorkItems'; +import type { BoardPhasesSnapshot } from '../useWorkItems'; const board = (workItems: WorkItem[]): BoardSnapshot => ({ workItems, runningSessionIds: [], parkedSessionIds: [] }); +/** The board the paged reads list: the two phases these cards sit in. */ +const BOARD = { id: 'work', phases: [{ id: 'intake' }, { id: 'execute' }] }; + const PROJECT_ID = 'project-1'; const ITEM_ID = 'item-1'; @@ -185,7 +189,7 @@ describe('useTransitionWorkItemMutation', () => { }); describe('useDeleteWorkItemMutation', () => { - it('drops the deleted card and its session marker from the board read', async () => { + it('drops the deleted card and its session marker from the cards the sidebar reads', async () => { let deleted = false; server.use( http.get(`${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/work-items`, () => @@ -202,17 +206,18 @@ describe('useDeleteWorkItemMutation', () => { ); const { result, client } = renderHookWithProviders(() => ({ - parked: useParkedSessions(PROJECT_ID), + cards: useSidebarWorkItemsQuery(PROJECT_ID), remove: useDeleteWorkItemMutation(PROJECT_ID), })); - await waitFor(() => expect(result.current.parked.has('session-1')).toBe(true)); + await waitFor(() => expect(result.current.cards.data?.parkedSessionIds).toEqual(['session-1'])); act(() => { result.current.remove.mutate(ITEM_ID); }); + await waitFor(() => expect(result.current.cards.data?.workItems).toEqual([])); await waitForMutationsIdle(client); - await waitFor(() => expect(result.current.parked.has('session-1')).toBe(false)); + await waitFor(() => expect(result.current.cards.data?.parkedSessionIds).toEqual([])); }); }); @@ -302,207 +307,335 @@ describe('useSessionWorkItemsQuery', () => { ), ); - const { result } = renderHookWithProviders(() => ({ - board: useWorkItemsQuery(PROJECT_ID), + const { result, client } = renderHookWithProviders(() => ({ session: useSessionWorkItemsQuery(PROJECT_ID, SESSION_ID), create: useUpsertWorkItemMutation(PROJECT_ID), })); - await waitFor(() => expect(result.current.board.data).toHaveLength(1)); await waitFor(() => expect(result.current.session.data).toHaveLength(1)); act(() => { result.current.create.mutate({ source: 'github-issue', sourceKey: 'github-issue:2', title: 'New card' }); }); - await waitFor(() => expect(result.current.board.data?.map(card => card.id)).toEqual(['item-2', ITEM_ID])); + await waitForMutationsIdle(client); + expect(result.current.create.isSuccess).toBe(true); expect(result.current.session.data?.map(card => card.id)).toEqual([ITEM_ID]); }); }); -describe('useWorkItemsQuery', () => { - const card = (id: string, title = id) => ({ +describe('useBoardPhasesQuery', () => { + const cardId = (number: number) => `00000000-0000-4000-8000-${String(number).padStart(12, '0')}`; + /** A card on the wire. Every write here lands in the same millisecond: when a card changed says nothing of what it holds. */ + const card = (number: number, title = `Card ${number}`) => ({ ...wireItem, - id, + id: cardId(number), title, - createdAt: `2026-07-0${id}T00:00:00.000Z`, - // A write stamps the card, here with a day per title. - changedAt: `2026-08-${String(10 + title.length)}T00:00:00.000Z`, + createdAt: new Date(Date.UTC(2026, 0, 1, 0, number)).toISOString(), + changedAt: '2026-08-11T00:00:00.000Z', }); - /** What moved, as the server answers it for the board it lists. */ - const moved = (workItems: object[], removedIds: string[], listed: Parameters[0]) => ({ - workItems, - removedIds, - check: boardCheck(listed), - }); - const titles = (cards: { title: string }[] | undefined) => cards?.map(item => item.title); - /** Answers the board reads in turn, and records the `since` each one sent. */ - function serveBoard(...answers: unknown[]) { - const sinces: Array = []; + const VIEW: BoardPhasesRequest = { board: 'work', sort: 'recent', q: '', filters: {}, windows: {} }; + + /** Serves the project's paged reads from `project.cards`, and records what the tab asked for. */ + function serveProject(cards: Array) { + const project = { cards, listings: new Array(), cardReads: new Array() }; server.use( - http.get(`${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/work-items`, async ({ request }) => { - sinces.push(new URL(request.url).searchParams.get('since')); - return HttpResponse.json((await answers[sinces.length - 1]) as object); + http.get(`${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/boards/:boardKey/phases`, ({ request, params }) => { + project.listings.push(new URL(request.url).searchParams); + return answerBoardPhases( + request, + { workItems: project.cards, boards: [BOARD], userId: 'user-1' }, + String(params.boardKey), + ); + }), + http.get(`${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/work-items`, ({ request }) => { + const ids = new URL(request.url).searchParams.getAll('workItemId'); + project.cardReads.push(ids); + return HttpResponse.json({ + workItems: project.cards.filter(listed => ids.includes(listed.id)).map(versionedCard), + }); }), ); - return sinces; + return project; } /** What a feed frame does to the board. */ const refresh = (client: QueryClient) => client.invalidateQueries({ queryKey: queryKeys.workItems(PROJECT_ID) }); + const listed = (snapshot: BoardPhasesSnapshot | undefined, phase: string) => + snapshot?.phases.find(candidate => candidate.phase === phase); + const titles = (snapshot: BoardPhasesSnapshot | undefined) => + listed(snapshot, 'execute')?.ids.map(id => snapshot?.workItems.find(held => held.id === id)?.title); - it('reads the board whole, then merges what moved since its cursor into the cards it holds', async () => { - const sinces = serveBoard( - { workItems: [card('5'), card('4'), card('2'), card('1')], cursor: 'first' }, - { - ...moved( - [card('4', 'Renamed'), card('3'), card('6')], - ['5'], - [card('6'), card('4', 'Renamed'), card('3'), card('2'), card('1')], - ), - cursor: 'second', - }, - ); - const { result, client } = renderHookWithProviders(() => useWorkItemsQuery(PROJECT_ID)); - await waitFor(() => expect(titles(result.current.data)).toEqual(['5', '4', '2', '1'])); - const unchanged = result.current.data!.slice(2); + it('reads a board it holds no card of in one request, then downloads nothing while nothing changes', async () => { + const project = serveProject([card(1), card(2)]); + const { result, client } = renderHookWithProviders(() => useBoardPhasesQuery(PROJECT_ID, VIEW)); + await waitFor(() => expect(titles(result.current.data)).toEqual(['Card 2', 'Card 1'])); + const snapshot = result.current.data; await act(() => refresh(client)); - await waitFor(() => expect(titles(result.current.data)).toEqual(['6', 'Renamed', '3', '2', '1'])); - expect(sinces).toEqual([null, 'first']); - // Each sits where another card did: sharing by position would have rebuilt them. - expect(result.current.data![3]).toBe(unchanged[0]); - expect(result.current.data![4]).toBe(unchanged[1]); + expect(project.listings.map(asked => asked.get('cards'))).toEqual(['true', null]); + expect(project.cardReads).toEqual([]); + // Nothing changed: whatever renders the board has nothing to render again. + expect(result.current.data).toBe(snapshot); }); - it('takes a whole board whenever the server sends one, as one that ignores `since` does', async () => { - const sinces = serveBoard( - { workItems: [card('1')], cursor: 'first' }, - { workItems: [card('2'), card('1')] }, - { workItems: [card('2'), card('1')] }, - ); - const { result, client } = renderHookWithProviders(() => useWorkItemsQuery(PROJECT_ID)); - await waitFor(() => expect(titles(result.current.data)).toEqual(['1'])); + it('downloads only the cards that changed or appeared, and keeps every other card the object it held', async () => { + const project = serveProject([card(1), card(2), card(3)]); + const { result, client } = renderHookWithProviders(() => useBoardPhasesQuery(PROJECT_ID, VIEW)); + await waitFor(() => expect(titles(result.current.data)).toEqual(['Card 3', 'Card 2', 'Card 1'])); + const held = (number: number) => result.current.data?.workItems.find(item => item.id === cardId(number)); + const [first, third] = [held(1), held(3)]; + // Renamed in the millisecond it was last written in. + project.cards = [card(1), card(2, 'Renamed'), card(3), card(4)]; await act(() => refresh(client)); - await waitFor(() => expect(titles(result.current.data)).toEqual(['2', '1'])); - const cards = result.current.data; - await act(() => refresh(client)); - await waitForMutationsIdle(client); - expect(sinces).toEqual([null, 'first', null]); - expect(result.current.data).toBe(cards); + await waitFor(() => expect(titles(result.current.data)).toEqual(['Card 4', 'Card 3', 'Renamed', 'Card 1'])); + expect(project.cardReads.map(ids => ids.toSorted())).toEqual([[cardId(2), cardId(4)]]); + expect(held(1)).toBe(first); + expect(held(3)).toBe(third); + expect(listed(result.current.data, 'execute')?.total).toBe(4); }); - it.each([ - ['an edit', [card('1', 'Renamed')]], - ['a card', [card('2'), card('1')]], - ['a removal', []], - ])('reads the board whole once when the server lists %s it was never sent', async (_missed, listed) => { - const sinces = serveBoard( - { workItems: [card('1')], cursor: 'first' }, - { ...moved([], [], listed), cursor: 'second' }, - { workItems: listed, cursor: 'third' }, - { ...moved([], [], listed), cursor: 'third' }, - ); - const { result, client } = renderHookWithProviders(() => useWorkItemsQuery(PROJECT_ID)); - await waitFor(() => expect(titles(result.current.data)).toEqual(['1'])); + it('stops listing a card the server no longer holds, without asking for any card', async () => { + const project = serveProject([card(1), card(2)]); + const { result, client } = renderHookWithProviders(() => useBoardPhasesQuery(PROJECT_ID, VIEW)); + await waitFor(() => expect(titles(result.current.data)).toEqual(['Card 2', 'Card 1'])); - await act(() => refresh(client)); - await waitFor(() => expect(titles(result.current.data)).toEqual(titles(listed))); + project.cards = [card(1)]; await act(() => refresh(client)); - expect(sinces).toEqual([null, 'first', null, 'third']); + await waitFor(() => expect(titles(result.current.data)).toEqual(['Card 1'])); + expect(project.cardReads).toEqual([]); + expect(result.current.data?.boardTotal).toBe(1); }); - it('reads the board whole while a mutation that writes no card is pending', async () => { - const sinces = serveBoard( - { workItems: [card('1')], cursor: 'first' }, - { ...moved([], [], [card('1', 'Renamed')]), cursor: 'second' }, - { workItems: [card('1', 'Renamed')], cursor: 'third' }, - ); - const { result, client } = renderHookWithProviders(() => ({ - cards: useWorkItemsQuery(PROJECT_ID), - other: useMutation({ mutationFn: () => new Promise(() => {}) }), - })); - await waitFor(() => expect(titles(result.current.cards.data)).toEqual(['1'])); - act(() => result.current.other.mutate()); - await waitFor(() => expect(client.isMutating()).toBe(1)); + it('drops a card deleted between the listing that names its new body and the read of that body, not showing the body it held', async () => { + const project = serveProject([card(1), card(2)]); + const { result, client } = renderHookWithProviders(() => useBoardPhasesQuery(PROJECT_ID, VIEW)); + await waitFor(() => expect(titles(result.current.data)).toEqual(['Card 2', 'Card 1'])); - await act(() => refresh(client)); - - await waitFor(() => expect(titles(result.current.cards.data)).toEqual(['Renamed'])); - expect(sinces).toEqual([null, 'first', null]); - }); - - it('keeps a change the server has not answered through a merge, and drops it once the server refuses', async () => { - let refuse!: () => void; - let answerLate!: (answer: object) => void; - const refusal = new Promise(resolve => (refuse = resolve)); - const lateAnswer = new Promise(resolve => (answerLate = resolve)); - const nothingMoved = moved([], [], [card('2'), card('1')]); - const sinces = serveBoard( - { workItems: [card('2'), card('1')], cursor: 'first' }, - { ...nothingMoved, cursor: 'second' }, - lateAnswer, - { workItems: [card('2'), card('1')], cursor: 'fourth' }, - ); + // The listing names the renamed card; it is deleted before the tab reads its body. + project.cards = [card(1), card(2, 'Renamed')]; server.use( - http.patch(`${TEST_BASE_URL}/web/factory/work-items/1`, async () => { + http.get(`${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/work-items`, ({ request }) => { + project.cardReads.push(new URL(request.url).searchParams.getAll('workItemId')); + return HttpResponse.json({ workItems: [] }); + }), + ); + await act(() => refresh(client)); + + await waitFor(() => expect(project.cardReads).toEqual([[cardId(2)]])); + await waitFor(() => expect(titles(result.current.data)).toEqual(['Card 1'])); + expect(result.current.data?.workItems.map(held => held.id)).toEqual([cardId(1)]); + }); + + it('lists a phase deeper by downloading only the cards past the ones it holds', async () => { + const project = serveProject(Array.from({ length: 60 }, (_, index) => card(index + 1))); + const { result, rerender } = renderHookWithProviders( + (windows: BoardPhasesRequest['windows']) => useBoardPhasesQuery(PROJECT_ID, { ...VIEW, windows }), + { initialProps: VIEW.windows }, + ); + await waitFor(() => expect(listed(result.current.data, 'execute')).toMatchObject({ total: 60 })); + expect(listed(result.current.data, 'execute')?.ids).toHaveLength(50); + + rerender({ execute: 100 }); + // The phase keeps its cards while the deeper listing loads. + expect(listed(result.current.data, 'execute')?.ids).toHaveLength(50); + + await waitFor(() => expect(listed(result.current.data, 'execute')?.ids).toHaveLength(60)); + expect(project.listings.at(-1)?.getAll('window')).toEqual(['execute:100']); + expect(project.listings.at(-1)?.has('cards')).toBe(false); + expect(project.cardReads).toHaveLength(1); + expect(project.cardReads[0]?.toSorted()).toEqual(Array.from({ length: 10 }, (_, index) => cardId(index + 1))); + }); + + it('asks the server for another view of a board it holds, and downloads no card it already has', async () => { + const project = serveProject([card(1, 'Fix login'), card(2, 'Ship billing')]); + const { result, rerender } = renderHookWithProviders( + (q: string) => useBoardPhasesQuery(PROJECT_ID, { ...VIEW, q }), + { initialProps: '' }, + ); + await waitFor(() => expect(titles(result.current.data)).toEqual(['Ship billing', 'Fix login'])); + + rerender('login'); + + await waitFor(() => expect(titles(result.current.data)).toEqual(['Fix login'])); + expect(project.listings.at(-1)?.get('q')).toBe('login'); + expect(project.cardReads).toEqual([]); + expect(result.current.data).toMatchObject({ matchingTotal: 1, boardTotal: 2 }); + }); + + it('keeps the open card when newer cards push it past the ones its phase lists, without listing the phase down to it', async () => { + const project = serveProject(Array.from({ length: 50 }, (_, index) => card(index + 1))); + const { result, rerender, client } = renderHookWithProviders( + (openCard: string | undefined) => useBoardPhasesQuery(PROJECT_ID, VIEW, openCard), + { initialProps: undefined }, + ); + await waitFor(() => expect(listed(result.current.data, 'execute')?.ids.at(-1)).toBe(cardId(1))); + const held = () => result.current.data?.workItems.find(item => item.id === cardId(1)); + const opened = held(); + + rerender(cardId(1)); + expect(project.listings).toHaveLength(1); + + project.cards = [...project.cards, card(51), card(52)]; + await act(() => refresh(client)); + + await waitFor(() => expect(listed(result.current.data, 'execute')?.total).toBe(52)); + expect(project.listings.at(-1)?.get('item')).toBe(cardId(1)); + // The phase lists its first cards, and the answer says apart that it holds the open one. + expect(listed(result.current.data, 'execute')?.ids).toHaveLength(50); + expect(listed(result.current.data, 'execute')?.ids).not.toContain(cardId(1)); + expect(result.current.data?.asked).toEqual({ id: cardId(1), phases: ['execute'] }); + expect(held()).toBe(opened); + expect(project.cardReads.map(ids => ids.toSorted())).toEqual([[cardId(51), cardId(52)]]); + + // Closed, the card is listed like any other: the board lets go of it. + rerender(undefined); + await act(() => refresh(client)); + + await waitFor(() => expect(result.current.data?.asked).toBeUndefined()); + expect(project.listings.at(-1)?.has('item')).toBe(false); + expect(held()).toBeUndefined(); + }); + + it('reads a linked card deep in its phase with the first cards of the board, not with the cards above it', async () => { + const project = serveProject(Array.from({ length: 120 }, (_, index) => card(index + 1))); + const { result } = renderHookWithProviders(() => useBoardPhasesQuery(PROJECT_ID, { ...VIEW, item: cardId(1) })); + + await waitFor(() => expect(result.current.data?.asked).toEqual({ id: cardId(1), phases: ['execute'] })); + expect(project.listings.map(asked => [asked.get('item'), asked.get('cards')])).toEqual([[cardId(1), 'true']]); + expect(project.cardReads).toEqual([]); + expect(listed(result.current.data, 'execute')).toMatchObject({ total: 120 }); + expect(listed(result.current.data, 'execute')?.ids).toHaveLength(50); + // Fifty listed cards and the linked one: the sixty-nine cards between them stay on the server. + expect(result.current.data?.workItems).toHaveLength(51); + expect(result.current.data?.workItems.at(-1)?.title).toBe('Card 1'); + }); + + it('reads the body of a card asked for on a board it holds, when it does not hold that card', async () => { + const project = serveProject(Array.from({ length: 120 }, (_, index) => card(index + 1))); + const { result, rerender } = renderHookWithProviders( + (item: string | undefined) => useBoardPhasesQuery(PROJECT_ID, { ...VIEW, ...(item ? { item } : {}) }), + { initialProps: undefined }, + ); + await waitFor(() => expect(listed(result.current.data, 'execute')?.ids).toHaveLength(50)); + + rerender(cardId(1)); + + await waitFor(() => expect(result.current.data?.asked).toEqual({ id: cardId(1), phases: ['execute'] })); + expect(project.cardReads).toEqual([[cardId(1)]]); + expect(result.current.data?.workItems.find(item => item.id === cardId(1))?.title).toBe('Card 1'); + }); + + it('keeps a change the server has not answered through a refresh, and drops it once the server refuses', async () => { + let refuse = () => {}; + const refusal = new Promise(resolve => { + refuse = resolve; + }); + serveProject([card(1), card(2)]); + server.use( + http.patch(`${TEST_BASE_URL}/web/factory/work-items/${cardId(1)}`, async () => { await refusal; return HttpResponse.json({ error: 'refused' }, { status: 409 }); }), ); const { result, client } = renderHookWithProviders(() => ({ - cards: useWorkItemsQuery(PROJECT_ID), + board: useBoardPhasesQuery(PROJECT_ID, VIEW), update: useUpdateWorkItemMutation(PROJECT_ID), })); - const parent = () => result.current.cards.data?.[1]?.parentWorkItemId; - await waitFor(() => expect(result.current.cards.data).toHaveLength(2)); + const parent = () => result.current.board.data?.workItems.find(item => item.id === cardId(1))?.parentWorkItemId; + await waitFor(() => expect(result.current.board.data?.workItems).toHaveLength(2)); - act(() => result.current.update.mutate({ id: '1', patch: { parentWorkItemId: '2' } })); - await waitFor(() => expect(parent()).toBe('2')); + act(() => result.current.update.mutate({ id: cardId(1), patch: { parentWorkItemId: cardId(2) } })); + await waitFor(() => expect(parent()).toBe(cardId(2))); await act(() => refresh(client)); - expect(sinces).toEqual([null, 'first']); - expect(parent()).toBe('2'); + expect(parent()).toBe(cardId(2)); - // The refusal lands while a read is out: its answer must not bring the change back. - act(() => void refresh(client)); - await waitFor(() => expect(sinces).toHaveLength(3)); refuse(); - await waitFor(() => expect(result.current.update.isError).toBe(true)); - answerLate({ ...nothingMoved, cursor: 'third' }); await waitForMutationsIdle(client); - expect(parent()).toBeNull(); - expect(sinces).toEqual([null, 'first', 'second', null]); }); - it('does not take a card being deleted here for a drifted board', async () => { - let finish!: () => void; - const finished = new Promise(resolve => (finish = resolve)); - const sinces = serveBoard( - { workItems: [card('2'), card('1')], cursor: 'first' }, - { ...moved([], [], [card('2'), card('1')]), cursor: 'second' }, - { ...moved([], ['1'], [card('2')]), cursor: 'third' }, - ); + it('takes a deleted card out of its phase and its counts before the server answers', async () => { + let finish = () => {}; + const finished = new Promise(resolve => { + finish = resolve; + }); + const project = serveProject([card(1), card(2)]); server.use( - http.delete(`${TEST_BASE_URL}/web/factory/work-items/1`, async () => { + http.delete(`${TEST_BASE_URL}/web/factory/work-items/${cardId(1)}`, async () => { await finished; + project.cards = [card(2)]; return HttpResponse.json({ ok: true }); }), ); const { result, client } = renderHookWithProviders(() => ({ - cards: useWorkItemsQuery(PROJECT_ID), + board: useBoardPhasesQuery(PROJECT_ID, VIEW), remove: useDeleteWorkItemMutation(PROJECT_ID), })); - await waitFor(() => expect(result.current.cards.data).toHaveLength(2)); + await waitFor(() => expect(titles(result.current.board.data)).toEqual(['Card 2', 'Card 1'])); - act(() => result.current.remove.mutate('1')); - await waitFor(() => expect(titles(result.current.cards.data)).toEqual(['2'])); - await act(() => refresh(client)); + act(() => result.current.remove.mutate(cardId(1))); + + await waitFor(() => expect(titles(result.current.board.data)).toEqual(['Card 2'])); + expect(result.current.board.data).toMatchObject({ matchingTotal: 1, boardTotal: 1 }); + expect(listed(result.current.board.data, 'execute')?.total).toBe(1); finish(); await waitForMutationsIdle(client); + expect(titles(result.current.board.data)).toEqual(['Card 2']); + }); - expect(titles(result.current.cards.data)).toEqual(['2']); - expect(sinces).toEqual([null, 'first', 'second']); + it('shows a card created here on top of its phase and counts it, without reading the board again', async () => { + const project = serveProject([card(1)]); + server.use( + http.post(`${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/work-items`, () => + HttpResponse.json({ workItem: { ...card(2, 'New card'), stages: ['intake'] } }), + ), + ); + const { result, client } = renderHookWithProviders(() => ({ + board: useBoardPhasesQuery(PROJECT_ID, VIEW), + create: useUpsertWorkItemMutation(PROJECT_ID), + })); + await waitFor(() => expect(titles(result.current.board.data)).toEqual(['Card 1'])); + + act(() => result.current.create.mutate({ source: 'manual', sourceKey: null, title: 'New card' })); + await waitForMutationsIdle(client); + + expect(listed(result.current.board.data, 'intake')).toEqual({ phase: 'intake', total: 1, ids: [cardId(2)] }); + expect(result.current.board.data).toMatchObject({ matchingTotal: 2, boardTotal: 2 }); + expect(project.listings).toHaveLength(1); + }); + + it('asks the server which searched view a card created here is in, and puts it on the view that searches nothing', async () => { + const project = serveProject([card(1, 'Fix login'), card(2, 'Ship billing')]); + const created = { ...card(3, 'New card'), stages: ['intake'] }; + server.use( + http.post(`${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/work-items`, () => { + project.cards = [...project.cards, created]; + return HttpResponse.json({ workItem: created }); + }), + ); + const { result, rerender, client } = renderHookWithProviders( + (q: string) => ({ + board: useBoardPhasesQuery(PROJECT_ID, { ...VIEW, q }), + create: useUpsertWorkItemMutation(PROJECT_ID), + }), + { initialProps: '' }, + ); + await waitFor(() => expect(titles(result.current.board.data)).toEqual(['Ship billing', 'Fix login'])); + rerender('login'); + await waitFor(() => expect(titles(result.current.board.data)).toEqual(['Fix login'])); + + act(() => result.current.create.mutate({ source: 'manual', sourceKey: null, title: 'New card' })); + await waitForMutationsIdle(client); + + // The search does not match the card: the server says so, and counts the board again. + await waitFor(() => expect(result.current.board.data).toMatchObject({ matchingTotal: 1, boardTotal: 3 })); + expect(listed(result.current.board.data, 'intake')).toEqual({ phase: 'intake', total: 0, ids: [] }); + expect(project.listings.map(asked => asked.get('q'))).toEqual([null, 'login', 'login']); + // Every card is in the view that searches nothing: it takes the card without being read again. + const whole = client.getQueryData(queryKeys.boardPhasesView(PROJECT_ID, VIEW)); + expect(listed(whole, 'intake')).toEqual({ phase: 'intake', total: 1, ids: [cardId(3)] }); + expect(whole).toMatchObject({ matchingTotal: 3, boardTotal: 3 }); }); }); diff --git a/mastracode/factory-ui/src/hooks/customBoardOperations.msw.test.tsx b/mastracode/factory-ui/src/hooks/customBoardOperations.msw.test.tsx index a399c39f565..2b6acaf9754 100644 --- a/mastracode/factory-ui/src/hooks/customBoardOperations.msw.test.tsx +++ b/mastracode/factory-ui/src/hooks/customBoardOperations.msw.test.tsx @@ -34,16 +34,6 @@ const item: WorkItem = { }; const wireItem = { ...item, factoryProjectId: 'fp-1', externalSource: null }; -function listHandler() { - return http.get('*/web/factory/projects/:id/work-items', () => - HttpResponse.json({ - workItems: [wireItem], - runningSessionIds: [], - parkedSessionIds: [], - }), - ); -} - describe('custom board operations', () => { beforeEach(() => { server.use(http.get('*/web/factory/projects/:id/boards', () => HttpResponse.json({ boards: [releaseBoard] }))); @@ -51,9 +41,9 @@ describe('custom board operations', () => { it.each(['shipping', 'shipped', 'execute'])('does not dispatch a drag to undeclared destination %s', async stage => { const transition = vi.fn(() => HttpResponse.json({})); - server.use(listHandler(), http.post('*/web/factory/projects/:id/work-items/:itemId/transition', transition)); + server.use(http.post('*/web/factory/projects/:id/work-items/:itemId/transition', transition)); const { result, client } = renderHookWithProviders(() => - useBoardItems({ factoryProjectId: 'fp-1', kind: 'release' }), + useBoardItems({ factoryProjectId: 'fp-1', kind: 'release', items: [item] }), ); await waitForMutationsIdle(client); act(() => @@ -77,8 +67,10 @@ describe('custom board operations', () => { }, }); }); - server.use(listHandler(), http.post('*/web/factory/projects/:id/work-items/:itemId/transition', transition)); - const { result, client } = renderHookWithProviders(() => useBoardItems({ factoryProjectId: 'fp-1', kind })); + server.use(http.post('*/web/factory/projects/:id/work-items/:itemId/transition', transition)); + const { result, client } = renderHookWithProviders(() => + useBoardItems({ factoryProjectId: 'fp-1', kind, items: [item] }), + ); await waitForMutationsIdle(client); act(() => result.current.handleDrop( @@ -108,7 +100,6 @@ describe('custom board operations', () => { let body: unknown; const transition = vi.fn(() => HttpResponse.json({})); server.use( - listHandler(), http.post('*/web/factory/projects/:id/work-items', async ({ request }) => { body = await request.json(); return HttpResponse.json({ workItem: { ...wireItem, id: 'release-2', source: 'linear-issue' } }); @@ -116,7 +107,7 @@ describe('custom board operations', () => { http.post('*/web/factory/projects/:id/work-items/:itemId/transition', transition), ); const { result, client } = renderHookWithProviders(() => - useBoardItems({ factoryProjectId: 'fp-1', kind: 'release' }), + useBoardItems({ factoryProjectId: 'fp-1', kind: 'release', items: [item] }), ); await waitForMutationsIdle(client); await act(async () => { @@ -148,7 +139,6 @@ describe('custom board operations', () => { const transition = vi.fn(() => HttpResponse.json({})); // The catalog never answers, so the hook cannot know the board's initial phase. server.use( - listHandler(), http.get('*/web/factory/projects/:id/boards', () => new Promise(() => {})), http.post('*/web/factory/projects/:id/work-items', async ({ request }) => { body = await request.json(); @@ -156,8 +146,9 @@ describe('custom board operations', () => { }), http.post('*/web/factory/projects/:id/work-items/:itemId/transition', transition), ); - const { result } = renderHookWithProviders(() => useBoardItems({ factoryProjectId: 'fp-1', kind: 'release' })); - await waitFor(() => expect(result.current.isPending).toBe(false)); + const { result } = renderHookWithProviders(() => + useBoardItems({ factoryProjectId: 'fp-1', kind: 'release', items: [item] }), + ); await act(async () => { result.current.handleDrop( { @@ -181,19 +172,11 @@ describe('custom board operations', () => { expect(transition).not.toHaveBeenCalled(); }); - it.each(['work', 'review', 'release'])('keeps persisted release cards isolated on %s', async kind => { - server.use(listHandler()); - const { result } = renderHookWithProviders(() => useBoardItems({ factoryProjectId: 'fp-1', kind })); - await waitFor(() => expect(result.current.isPending).toBe(false)); - expect(result.current.visible.map(card => card.id)).toEqual(kind === 'release' ? [item.id] : []); - }); - it.each(['approval_required', 'stale_revision'])( 'sends the persisted board and revision and preserves %s rejection', async code => { let body: unknown; server.use( - listHandler(), http.post('*/web/factory/projects/:id/work-items/:itemId/transition', async ({ request }) => { body = await request.json(); return HttpResponse.json({ @@ -201,12 +184,13 @@ describe('custom board operations', () => { }); }), ); - const { result } = renderHookWithProviders(() => useBoardItems({ factoryProjectId: 'fp-1', kind: 'release' })); - await waitFor(() => expect(result.current.visible).toHaveLength(1)); + const { result, client } = renderHookWithProviders(() => + useBoardItems({ factoryProjectId: 'fp-1', kind: 'release', items: [item] }), + ); + await waitForMutationsIdle(client); act(() => result.current.move(item.id, 'preparing')); await waitFor(() => expect(result.current.transitionReasons[item.id]).toBe(code)); expect(body).toMatchObject({ board: 'release', stage: 'preparing', expectedRevision: 4 }); - expect(result.current.visible[0].stages).toEqual(['queued']); }, ); diff --git a/mastracode/factory-ui/src/hooks/useWorkItems.ts b/mastracode/factory-ui/src/hooks/useWorkItems.ts index d18efbd01b2..6f9d2282e3b 100644 --- a/mastracode/factory-ui/src/hooks/useWorkItems.ts +++ b/mastracode/factory-ui/src/hooks/useWorkItems.ts @@ -1,7 +1,7 @@ import type { FactoryRuleStage } from '@mastra/factory/rules/types'; -import { boardCheck } from '@mastra/factory/work-items/board-check'; import type { QueryClient, QueryKey } from '@tanstack/react-query'; import { + keepPreviousData, queryOptions, replaceEqualDeep, skipToken, @@ -12,13 +12,17 @@ import { } from '@tanstack/react-query'; import { useApiConfig } from '../api/config'; -import { cardMoveMutationKey, cardWriteMutationKey, queryKeys } from '../api/keys'; +import { cardMoveMutationKey, cardWriteMutationKey, isUnnarrowedBoardView, queryKeys } from '../api/keys'; +import type { BoardPhasesRequest } from '../api/types'; import { activityDepth, activityStart } from '../ui/domains/factory/periodActivity'; import type { ActivityPeriod } from '../ui/domains/factory/periodActivity'; +import { itemBoard } from '../ui/domains/factory/boardStages'; import { createWorkItem, deleteWorkItem, fetchWorkItemActivity, + fetchBoardPhases, + fetchWorkItemFilterOptions, fetchWorkItemStarters, listWorkItems, transitionWorkItem, @@ -61,68 +65,204 @@ export function stripCachedSessionRefs(queryClient: QueryClient, factoryProjectI ); } -// Module-level so React Query can cache each derived value instead of -// rebuilding it (and, for the set, breaking referential equality) per render. +// Module-level so React Query can cache the derived value instead of rebuilding it per render. const selectCards = (board: BoardSnapshot) => board.workItems; -const selectParkedSessions = (board: BoardSnapshot): ReadonlySet => new Set(board.parkedSessionIds); -const NO_SESSIONS: ReadonlySet = new Set(); -/** - * Reads the board: whole the first time, then only what moved since the cursor of the board - * held, merged into the board held when the answer arrives. That board carries the changes - * made here that the server has not answered and none it refused. A card the answer leaves - * equal stays the object held, so nothing showing it renders again. - */ -async function readBoard( - baseUrl: string, - factoryProjectId: string, - signal: AbortSignal, - client: QueryClient, - whole = false, -): Promise { - const held = () => client.getQueryData(queryKeys.workItems(factoryProjectId)); - const since = whole ? undefined : held()?.cursor; - const only = since ? { since } : undefined; - const { removedIds, check, ...read } = await listWorkItems(baseUrl, factoryProjectId, signal, only); - const board = held(); - const byId = new Map(board?.workItems.map(card => [card.id, card])); - let cards = read.workItems.map(card => replaceEqualDeep(byId.get(card.id), card)); - if (removedIds) { - for (const card of cards) byId.set(card.id, card); - for (const id of removedIds) byId.delete(id); - cards = [...byId.values()]; - // What moved fits only the board its cursor names, and leaves the board the server checks - // once every card written here is answered. Otherwise this copy drifted: read it whole. - const writing = client.isMutating({ mutationKey: cardWriteMutationKey(factoryProjectId) }); - if (board?.cursor !== since || (check !== boardCheck(cards) && !writing)) { - return readBoard(baseUrl, factoryProjectId, signal, client, true); - } - // The order a whole read lists them in: newest first, then by id. - cards.sort((a, b) => (a.createdAt + a.id < b.createdAt + b.id ? 1 : -1)); - } - if (!board) return { ...read, workItems: cards }; - const same = cards.length === board.workItems.length && cards.every((card, i) => card === board.workItems[i]); - return same ? replaceEqualDeep(board, { ...read, workItems: board.workItems }) : { ...read, workItems: cards }; -} - -/** - * The board: its cards and the sessions parked on them. `scope` narrows it to the cards holding a - * session, with the cards related to them. - */ -export function boardQueryOptions(baseUrl: string, factoryProjectId: string | undefined, scope?: 'sessions') { +/** The cards holding a session, with the cards related to them, and the sessions parked on them. */ +export function sessionCardsQueryOptions(baseUrl: string, factoryProjectId: string | undefined) { return queryOptions({ - queryKey: scope ? queryKeys.workItemsWithSessions(factoryProjectId) : queryKeys.workItems(factoryProjectId), + queryKey: queryKeys.workItemsWithSessions(factoryProjectId), queryFn: factoryProjectId - ? ({ signal, client }) => - scope - ? listWorkItems(baseUrl, factoryProjectId, signal, { scope }) - : readBoard(baseUrl, factoryProjectId, signal, client) + ? ({ signal }) => listWorkItems(baseUrl, factoryProjectId, signal, { scope: 'sessions' }) : skipToken, // The feed provider refreshes this. A hidden tab holds no stream and polls nothing, so refresh immediately on return. refetchOnWindowFocus: true, - // `readBoard` shares cards by id. React Query shares by index, which would rebuild every card - // after an added or removed one. - structuralSharing: !!scope, + }); +} + +/** A phase of a board view: the cards it lists, in the view's order, of the `total` that match. */ +export interface ListedPhase { + phase: string; + total: number; + ids: string[]; +} + +/** + * One view of a board as of one read: which cards each phase lists, how many match, and in + * `workItems` the body of every listed card, of the asked card and of the cards related to them. + */ +export interface BoardPhasesSnapshot extends BoardSnapshot { + phases: ListedPhase[]; + /** + * The card the read asked for, and the phases of the view that hold it, listed there or deeper. + * Absent when the board does not hold the card; in no phase when the view leaves it out. + */ + asked?: { id: string; phases: string[] }; + /** How many of the board's cards match the view's search and filters. */ + matchingTotal: number; + /** How many cards the board holds, whatever the view. */ + boardTotal: number; +} + +/** The most ids one `workItemId` read may name. */ +const CARDS_PER_READ = 100; + +/** The cards among `ids` the server still holds, read by id. */ +async function readCards(baseUrl: string, factoryProjectId: string, ids: string[], signal: AbortSignal) { + const reads: Promise[] = []; + for (let start = 0; start < ids.length; start += CARDS_PER_READ) { + const workItemId = ids.slice(start, start + CARDS_PER_READ); + reads.push(listWorkItems(baseUrl, factoryProjectId, signal, { workItemId })); + } + return (await Promise.all(reads)).flatMap(read => read.workItems); +} + +/** + * The card the tab holds for each id of `versions`, from whichever read cached it. Where several + * reads hold a card, the one whose body is the version named wins. + */ +function heldCards(client: QueryClient, factoryProjectId: string, versions: ReadonlyMap) { + const held = new Map(); + const snapshots = client.getQueriesData({ queryKey: queryKeys.workItems(factoryProjectId) }); + for (const [, snapshot] of snapshots) { + for (const card of snapshot?.workItems ?? []) { + const version = versions.get(card.id); + if (version === undefined) continue; + const holder = held.get(card.id); + if (!holder || (card.version === version && holder.version !== version)) held.set(card.id, card); + } + } + return held; +} + +/** + * Reads one view of a board. The server names the cards of each phase with the version of the + * body it would send for each; only the cards the tab does not hold at that version are + * downloaded, by id. The first read of a board holds none, so it asks for the bodies with the + * listing. A card the read leaves equal stays the object held, so nothing showing it renders + * again, and a read that changes nothing answers the snapshot held. `openCard` is asked for in + * place of the card the view names: the answer says which phases hold it, however deep. + */ +async function readBoardPhases( + baseUrl: string, + factoryProjectId: string, + request: BoardPhasesRequest, + openCard: string | undefined, + signal: AbortSignal, + client: QueryClient, +): Promise { + const boardHeld = client + .getQueriesData({ queryKey: queryKeys.boardPhases(factoryProjectId, request.board) }) + .some(([, snapshot]) => snapshot !== undefined); + const asked = openCard ? { ...request, item: openCard } : request; + const answer = await fetchBoardPhases(baseUrl, factoryProjectId, asked, !boardHeld, signal); + const named = [ + ...answer.phases.flatMap(phase => phase.cards), + ...(answer.item ? [answer.item] : []), + ...answer.related, + ]; + const versions = new Map(named.map(card => [card.id, card.version])); + const read = new Map(answer.workItems?.map(card => [card.id, card])); + const heldAtAnswer = heldCards(client, factoryProjectId, versions); + const stale = [...versions].flatMap(([id, version]) => + read.has(id) || heldAtAnswer.get(id)?.version === version ? [] : [id], + ); + if (stale.length > 0) { + for (const card of await readCards(baseUrl, factoryProjectId, stale, signal)) { + if (versions.has(card.id)) read.set(card.id, card); + } + } + // Read again: the cards held carry the changes made here while the server answered. + const held = heldCards(client, factoryProjectId, versions); + const cards = new Map(); + // A card the server holds no body of was deleted since the listing: no phase shows it, and the + // older body the tab holds is not it. + const deleted = new Set(stale.filter(id => !read.has(id))); + for (const id of versions.keys()) { + if (deleted.has(id)) continue; + const body = read.get(id); + const card = body ? replaceEqualDeep(held.get(id), body) : held.get(id); + if (card) cards.set(id, card); + } + const answered = answer.item; + const listing = { + phases: answer.phases.map(listed => ({ + phase: listed.phase, + total: listed.total, + ids: listed.cards.flatMap(({ id }) => (cards.has(id) ? [id] : [])), + })), + ...(answered && cards.has(answered.id) + ? { asked: { id: answered.id, phases: answered.places.map(place => place.phase) } } + : {}), + matchingTotal: answer.matchingTotal, + boardTotal: answer.boardTotal, + runningSessionIds: answer.runningSessionIds, + parkedSessionIds: answer.parkedSessionIds, + }; + const workItems = [...cards.values()]; + const previous = client.getQueryData(queryKeys.boardPhasesView(factoryProjectId, request)); + if (!previous) return { ...listing, workItems }; + const { workItems: previousCards, ...previousListing } = previous; + const sameCards = + workItems.length === previousCards.length && workItems.every((card, i) => card === previousCards[i]); + const sharedListing = replaceEqualDeep(previousListing, listing); + if (sameCards && sharedListing === previousListing) return previous; + return { ...sharedListing, workItems: sameCards ? previousCards : workItems }; +} + +/** + * One view of a board: its phases, and the cards they list. `openCard` is the card whose details + * the page holds open: every read asks for it, so a refresh or a new order never takes it off the + * page, however deep its phase holds it. It stays out of the key, because the view is the same + * with a card open: opening or closing one reads nothing. + */ +export function boardPhasesQueryOptions( + baseUrl: string, + factoryProjectId: string | undefined, + request: BoardPhasesRequest, + openCard?: string, +) { + return queryOptions({ + queryKey: queryKeys.boardPhasesView(factoryProjectId, request), + queryFn: factoryProjectId + ? ({ signal, client }) => readBoardPhases(baseUrl, factoryProjectId, request, openCard, signal, client) + : skipToken, + // The feed provider refreshes this. A hidden tab holds no stream and polls nothing, so refresh immediately on return. + refetchOnWindowFocus: true, + // `readBoardPhases` shares cards by id. React Query shares by index, which would rebuild + // every card after an added or removed one. + structuralSharing: false, + }); +} + +/** The labels and people the project's cards can be filtered by. */ +export function workItemFilterOptionsQueryOptions(baseUrl: string, factoryProjectId: string | undefined) { + return queryOptions({ + queryKey: queryKeys.workItemFilterOptions(factoryProjectId), + queryFn: factoryProjectId + ? ({ signal }) => fetchWorkItemFilterOptions(baseUrl, factoryProjectId, signal) + : skipToken, + // Refreshed with the board, by the feed provider and on return to a hidden tab. + refetchOnWindowFocus: true, + }); +} + +/** Which cards are filed from `sources`, with the sources the answer covers. */ +export interface FiledFromAnswer extends BoardSnapshot { + sources: readonly string[]; +} + +/** The cards filed from any of `sources`: source ids or URLs, at most a hundred. */ +export function filedFromQueryOptions(baseUrl: string, factoryProjectId: string | undefined, sources: string[]) { + return queryOptions({ + queryKey: queryKeys.workItemsFiledFrom(factoryProjectId, sources), + queryFn: + factoryProjectId && sources.length > 0 + ? async ({ signal }): Promise => ({ + ...(await listWorkItems(baseUrl, factoryProjectId, signal, { source: sources })), + sources, + }) + : skipToken, }); } @@ -153,12 +293,6 @@ export function workItemActivityQueryOptions(baseUrl: string, factoryProjectId: }); } -/** The org's persisted work items (kanban cards) for a project. */ -export function useWorkItemsQuery(factoryProjectId: string | undefined) { - const { baseUrl } = useApiConfig(); - return useQuery({ ...boardQueryOptions(baseUrl, factoryProjectId), select: selectCards }); -} - /** * The cards holding one session, with the cards related to them: what a session page reads * instead of the board. @@ -177,32 +311,83 @@ export function useSessionWorkItemsQuery(factoryProjectId: string | undefined, s }); } -/** - * The cards the sidebar marks its sessions with. A page that loads the board shares that read; - * any other asks only for the cards holding a session. - */ -export function useSidebarWorkItemsQuery(factoryProjectId: string | undefined, boardOnPage: boolean) { +/** The cards the sidebar marks its sessions with: the ones holding a session, with the cards related to them. */ +export function useSidebarWorkItemsQuery(factoryProjectId: string | undefined) { const { baseUrl } = useApiConfig(); - const queryClient = useQueryClient(); - const board = boardQueryOptions(baseUrl, factoryProjectId); - const withSessions = boardQueryOptions(baseUrl, factoryProjectId, 'sessions'); + return useQuery(sessionCardsQueryOptions(baseUrl, factoryProjectId)); +} + +/** + * One view of a board. Changing the view keeps the phases shown until the new ones answer. A view + * the tab read while `openCard` was closed may hold it below what its phases list: that read is + * not shown over the open card. The view is read for the card instead, and the card stays on the + * page until the answer says where it is. + */ +export function useBoardPhasesQuery( + factoryProjectId: string | undefined, + request: BoardPhasesRequest, + openCard?: string, +) { + const { baseUrl } = useApiConfig(); + const held = useQueryClient().getQueryData(queryKeys.boardPhasesView(factoryProjectId, request)); + const heldWithoutOpenCard = openCard !== undefined && held?.workItems.every(card => card.id !== openCard); return useQuery({ - ...(boardOnPage ? board : withSessions), - // Moving between the two keeps the other list's marks until this one answers. - placeholderData: () => queryClient.getQueryData((boardOnPage ? withSessions : board).queryKey), + ...boardPhasesQueryOptions( + baseUrl, + factoryProjectId, + heldWithoutOpenCard ? { ...request, item: openCard } : request, + openCard, + ), + placeholderData: keepPreviousData, }); } -/** Sessions parked on a plan or a question, read with the cards so a card and its marker agree. */ -export function useParkedSessions(factoryProjectId: string | undefined): ReadonlySet { +/** The labels and people the board's filter menus offer. */ +export function useWorkItemFilterOptionsQuery(factoryProjectId: string | undefined) { const { baseUrl } = useApiConfig(); - const { data } = useQuery({ ...boardQueryOptions(baseUrl, factoryProjectId), select: selectParkedSessions }); - return data ?? NO_SESSIONS; + return useQuery(workItemFilterOptionsQueryOptions(baseUrl, factoryProjectId)); +} + +/** The snapshot listing `item` on top of the phases it sits in, where it does not list it yet. */ +function withCardOnTop(snapshot: BoardPhasesSnapshot, item: WorkItem): BoardPhasesSnapshot { + if (snapshot.phases.some(listed => listed.ids.includes(item.id))) return snapshot; + const sitsInAPhase = snapshot.phases.some(listed => item.stages.includes(listed.phase)); + return { + ...snapshot, + workItems: [item, ...snapshot.workItems.filter(card => card.id !== item.id)], + // A card in no phase of its board shows in the first one, where cards start. + phases: snapshot.phases.map((listed, index) => + (sitsInAPhase ? item.stages.includes(listed.phase) : index === 0) + ? { ...listed, ids: [item.id, ...listed.ids], total: listed.total + 1 } + : listed, + ), + matchingTotal: snapshot.matchingTotal + 1, + boardTotal: snapshot.boardTotal + 1, + }; +} + +/** The cached cards without the card `id`, which the phases that listed it no longer count. */ +function withoutCard(cached: BoardSnapshot | BoardPhasesSnapshot, id: string): BoardSnapshot | BoardPhasesSnapshot { + const workItems = cached.workItems.filter(card => card.id !== id); + if (!('phases' in cached) || !cached.phases.some(listed => listed.ids.includes(id))) { + return { ...cached, workItems }; + } + return { + ...cached, + workItems, + phases: cached.phases.map(listed => + listed.ids.includes(id) + ? { ...listed, ids: listed.ids.filter(other => other !== id), total: listed.total - 1 } + : listed, + ), + matchingTotal: cached.matchingTotal - 1, + boardTotal: cached.boardTotal - 1, + }; } /** * Materialize a work item (the server upserts on `sourceKey`, so acting twice - * on the same issue reuses the card). The list cache is patched in place. + * on the same issue reuses the card). The cached cards are patched in place. */ export function useUpsertWorkItemMutation(factoryProjectId: string | undefined) { const { baseUrl } = useApiConfig(); @@ -212,11 +397,29 @@ export function useUpsertWorkItemMutation(factoryProjectId: string | undefined) mutationFn: (input: CreateWorkItemInput) => createWorkItem(baseUrl, requireFactoryProjectId(factoryProjectId), input), onSuccess: item => { - const boardKey = queryKeys.workItems(factoryProjectId); - // A session's cards take the saved card only where they hold it; a new card joins the board alone. - patchCards(queryClient, boardKey, cards => cards.map(card => (card.id === item.id ? item : card))); - queryClient.setQueryData(boardKey, board => - board ? { ...board, workItems: [item, ...board.workItems.filter(card => card.id !== item.id)] } : undefined, + // A session's cards take the saved card only where they hold it; a new card joins its board alone. + patchCards(queryClient, queryKeys.workItems(factoryProjectId), cards => + cards.map(card => (card.id === item.id ? item : card)), + ); + // Only the server knows whether a card matches a search or a filter: the view with neither + // takes the card, and the server is asked for the others again. + const boardKey = queryKeys.boardPhases(factoryProjectId, itemBoard(item)); + queryClient.setQueriesData( + { queryKey: boardKey, predicate: query => isUnnarrowedBoardView(query.queryKey) }, + snapshot => snapshot && withCardOnTop(snapshot, item), + ); + void queryClient.invalidateQueries({ + queryKey: boardKey, + predicate: query => !isUnnarrowedBoardView(query.queryKey), + }); + // Whoever asked which cards are filed from this one's source learns of it without asking again. + queryClient.setQueriesData( + { queryKey: queryKeys.workItemsFiledFromAny(factoryProjectId) }, + answer => { + const filedFromAsked = answer?.sources.some(source => source === item.sourceKey || source === item.url); + if (!answer || !filedFromAsked || answer.workItems.some(card => card.id === item.id)) return answer; + return { ...answer, workItems: [item, ...answer.workItems] }; + }, ); }, }); @@ -298,9 +501,6 @@ export function useTransitionWorkItemMutation(factoryProjectId: string | undefin }), onMutate: async ({ item, stage, reenter = false }) => { await queryClient.cancelQueries({ queryKey: listKey }); - const previousItem = queryClient - .getQueryData(listKey) - ?.workItems.find(candidate => candidate.id === item.id); const enteredAt = new Date().toISOString(); const actor = currentUserId ?? 'factory:optimistic'; patchCards(queryClient, listKey, cards => @@ -314,15 +514,14 @@ export function useTransitionWorkItemMutation(factoryProjectId: string | undefin : candidate, ), ); - return { previousItem, enteredAt, actor }; + return { enteredAt, actor }; }, - onError: (_error, variables, context) => { - const previousItem = context?.previousItem; - if (!previousItem) return; + // The card the move was asked of is the one held before it: every read holds cards by revision. + onError: (_error, variables) => { patchCards(queryClient, listKey, cards => cards.map(item => { if (item.id !== variables.item.id || item.revision !== variables.item.revision) return item; - return previousItem; + return variables.item; }), ); }, @@ -330,9 +529,9 @@ export function useTransitionWorkItemMutation(factoryProjectId: string | undefin patchCards(queryClient, listKey, cards => cards.map(item => { if (item.id !== variables.item.id || item.revision !== variables.item.revision) return item; - if (result.status === 'rejected') return context?.previousItem ?? item; + if (result.status === 'rejected') return variables.item; if (result.revision <= item.revision) return item; - const previousItem = context?.previousItem ?? variables.item; + const previousItem = variables.item; return { ...item, stages: [result.stage], @@ -344,6 +543,8 @@ export function useTransitionWorkItemMutation(factoryProjectId: string | undefin variables.reenter ?? false, ), revision: result.revision, + // The server changed more of the card than its stage: the next read downloads it whatever version it names. + version: undefined, }; }), ); @@ -394,7 +595,10 @@ export function useDeleteWorkItemMutation(factoryProjectId: string | undefined) onMutate: async id => { await queryClient.cancelQueries({ queryKey: listKey }); const previous = queryClient.getQueriesData({ queryKey: listKey }); - patchCards(queryClient, listKey, cards => cards.filter(item => item.id !== id)); + queryClient.setQueriesData( + { queryKey: listKey }, + cached => cached && withoutCard(cached, id), + ); return { previous }; }, onError: (_err, _id, context) => { diff --git a/mastracode/factory-ui/src/ui/__tests__/AppStartup.msw.test.tsx b/mastracode/factory-ui/src/ui/__tests__/AppStartup.msw.test.tsx index 8905466ee6c..8cf47c4046d 100644 --- a/mastracode/factory-ui/src/ui/__tests__/AppStartup.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/__tests__/AppStartup.msw.test.tsx @@ -10,6 +10,7 @@ import { createMemoryRouter, RouterProvider } from 'react-router'; import { describe, expect, it, onTestFinished, vi } from 'vitest'; import { builtinBoardCatalog, releaseBoard } from '../../../e2e/ui/board-catalog'; +import { answerBoardPhases, answerWorkItemFilterOptions } from '../../../e2e/ui/board-reads'; import { listedRepository } from '../../../e2e/ui/factory-projects'; import { server } from '../../../e2e/ui/msw-server'; import { renderWithProviders, TEST_API, TEST_BASE_URL, waitForMutationsIdle } from '../../../e2e/ui/render'; @@ -21,6 +22,7 @@ const AUTH_ME_URL = `${TEST_BASE_URL}/auth/me`; const PROJECTS_URL = `${TEST_BASE_URL}/web/factory/projects`; const linkedFactory = { ...factory, repositories: [listedRepository('project-repo-1', 'octo/app')] }; const emptyFactory = { ...factory, repositories: [] }; +const BOARDS = [...builtinBoardCatalog.boards, releaseBoard]; // Requests keyed by another response or by state a component resolves, so // they go out once the page that reads them renders. @@ -33,20 +35,27 @@ const STARTED_BY_THE_PAGE = [ /^GET \/web\/config\/models\b/, // The board's issue and pull request lists: keyed by its repositories and intake settings. /^GET \/web\/github\/projects\/[^/]+\/(issues|prs)\b/, - // The board's recent activity: keyed by the people on its cards. + // The board's recent activity: keyed by the people the filter options name. /^GET \/web\/factory\/projects\/[^/]+\/audit\b/, ]; // Settings sections load their own data once they render; only their code starts early. const SETTINGS_SECTION_DATA = [/^GET \/api\/agent-controller\/code\/sessions\/factory-1$/]; const REREAD_ONCE_THE_FEED_CONNECTS = [ /^GET \/web\/factory\/projects\/[^/]+\/work-items\b/, + /^GET \/web\/factory\/projects\/[^/]+\/boards\/[^/]+\/phases\b/, /^GET \/web\/factory\/projects\/[^/]+\/decisions\b/, /^GET \/api\/agent-controller\/code\/active-runs$/, ]; const CARDS_URL = 'GET /web/factory/projects/factory-1/work-items'; -// A page that shows the board shares that one read with the sidebar; any other asks only for the cards holding a session. -const THE_BOARD = [CARDS_URL]; +// Any page asks for the cards holding a session, which its sidebar marks. const WITH_SESSIONS = [`${CARDS_URL}?scope=sessions`]; +const PROJECT_URL = 'GET /web/factory/projects/factory-1'; +// A board asks for its own phases, with the cards they list, and for what its filters offer: never for every card. +const boardOf = (board: string, view: string) => [ + ...WITH_SESSIONS, + `${PROJECT_URL}/boards/${board}/phases?${view}&cards=true`, + `${CARDS_URL}/filter-options`, +]; // A draft also asks the server for what its starters count and when cards came in and shipped, from a week back. const WITH_SESSIONS_AND_COUNTS = [...WITH_SESSIONS, `${CARDS_URL}/starters`, `${CARDS_URL}/activity?since=`]; @@ -66,8 +75,13 @@ function renderApp( HttpResponse.json({ models, fallbackModelId: models[0]?.id ?? null }), ), http.get(PROJECTS_URL, projects), - http.get(`${TEST_BASE_URL}/web/factory/projects/:factoryId/boards`, () => - HttpResponse.json({ boards: [...builtinBoardCatalog.boards, releaseBoard] }), + http.get(`${TEST_BASE_URL}/web/factory/projects/:factoryId/boards`, () => HttpResponse.json({ boards: BOARDS })), + // Answered here, not by the ambient handlers: those ask who is signed in, which this suite holds back. + http.get(`${TEST_BASE_URL}/web/factory/projects/:factoryId/boards/:boardKey/phases`, ({ request, params }) => + answerBoardPhases(request, { workItems: [], boards: BOARDS, userId: 'user-1' }, String(params.boardKey)), + ), + http.get(`${TEST_BASE_URL}/web/factory/projects/:factoryId/work-items/filter-options`, () => + answerWorkItemFilterOptions([]), ), // No ambient handler: the sidebar's sessions, the chat's permissions, the // composer's model defaults and the board's intake. @@ -128,10 +142,18 @@ function returnToTab() { describe('Opening Factory', () => { it.each([ - { page: 'Work', path: '/factories/factory-1/work', cards: THE_BOARD }, - // The retired Review board's links open Work, so they load what Work needs. - { page: 'Work from a Review board link', path: '/factories/factory-1/review', cards: THE_BOARD }, - { page: 'a custom board', path: '/factories/factory-1/boards/release', cards: THE_BOARD }, + { page: 'Work', path: '/factories/factory-1/work', cards: boardOf('work', 'sort=recent') }, + // The retired Review board's links open Work on its pull requests, so they load what that view needs. + { + page: 'Work from a Review board link', + path: '/factories/factory-1/review', + cards: boardOf('work', 'sort=recent&source=pull-request'), + }, + { + page: 'a custom board', + path: '/factories/factory-1/boards/release', + cards: boardOf('release', 'sort=recent'), + }, { page: 'Rules', path: '/factories/factory-1/rules?group=failed', cards: WITH_SESSIONS }, { page: 'a new session', path: '/factories/factory-1/new', cards: WITH_SESSIONS }, { @@ -145,7 +167,7 @@ describe('Opening Factory', () => { page: 'Work before a repository is linked', path: '/factories/factory-1/work', listed: emptyFactory, - cards: THE_BOARD, + cards: boardOf('work', 'sort=recent'), }, ])('loads everything $page needs during the sign-in check, once each', async ({ path, listed, models, cards }) => { const { requests, markSignInAnswered } = recordRequests(); @@ -186,11 +208,16 @@ describe('Opening Factory', () => { [...new Set(sent)].filter(url => sent.filter(other => other === url).length > timesNeeded(url)), 'requests sent more often than the page needs', ).toEqual([]); - expect([...new Set(sent.filter(url => url.startsWith(CARDS_URL)))], 'what the page asks about the cards').toEqual( - cards, - ); + const aboutCards = (url: string) => url.startsWith(CARDS_URL) || /\/boards\/[^/]+\/phases\b/.test(url); + expect([...new Set(sent.filter(aboutCards))], 'what the page asks about the cards').toEqual(cards); const unread = prefetched.filter(query => query.getObserversCount() === 0).map(query => query.queryHash); - expect(unread, 'queries started for the page but never read by it').toEqual([]); + // A board without a repository shows how to link one instead of its phases. Its reads left + // with the Factory list, before anything could say so, rather than a round trip later on every board. + const boardHidden = listed === emptyFactory; + expect( + unread.filter(hash => !(boardHidden && /"phases"|"filter-options"/.test(hash))), + 'queries started for the page but never read by it', + ).toEqual([]); }); it('loads the Factory list during the sign-in check from a link without a Factory', async () => { diff --git a/mastracode/factory-ui/src/ui/__tests__/BoardPagePagedReads.msw.test.tsx b/mastracode/factory-ui/src/ui/__tests__/BoardPagePagedReads.msw.test.tsx new file mode 100644 index 00000000000..4a604d8b883 --- /dev/null +++ b/mastracode/factory-ui/src/ui/__tests__/BoardPagePagedReads.msw.test.tsx @@ -0,0 +1,264 @@ +import { act, fireEvent, screen, waitFor, within } from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; +import { http, HttpResponse } from 'msw'; +import { createMemoryRouter, RouterProvider } from 'react-router'; +import { afterEach, beforeEach, describe, expect, it, onTestFinished, vi } from 'vitest'; +import { z } from 'zod'; + +import { isStubbedProjectRead } from '../../../e2e/ui/board-reads'; +import { server } from '../../../e2e/ui/msw-server'; +import { renderWithProviders, TEST_BASE_URL } from '../../../e2e/ui/render'; +import { queryKeys } from '../../api/keys'; +import { createAppRoutes } from '../router'; +import { boardViewport, mockBoardRowLayout } from './boardRowLayout'; +import { largeBoard, largeCardId } from './fixtures/largeBoard'; +import { FACTORY_ID, stubWorkBoard } from './workBoardStubs'; + +const CARDS_PATH = `/web/factory/projects/${FACTORY_ID}/work-items`; +const PHASES_PATH = `/web/factory/projects/${FACTORY_ID}/boards/work/phases`; + +const answeredCardsSchema = z.object({ workItems: z.array(z.unknown()).optional() }); + +/** + * Opens the Work board of a project holding `count` cards, in Triage unless `stageOf` says where, + * none of them with a session, and records what the page then asks the server about its cards. + * `link` is the query of the address the board is opened from. + */ +function openLargeBoard(count: number, stageOf: (index: number) => string = () => 'triage', link = '') { + const project = { cards: largeBoard(count).map((card, index) => ({ ...card, stages: [stageOf(index)] })) }; + const asked = { + listings: new Array(), + cardReads: new Array(), + wholeBoards: 0, + /** How many card bodies the answers to the page carried. */ + cardsDownloaded: 0, + }; + stubWorkBoard(); + server.use( + http.get(`${TEST_BASE_URL}${CARDS_PATH}`, ({ request }) => { + const query = new URL(request.url).searchParams; + if (query.has('scope') || query.has('source')) return HttpResponse.json({ workItems: [] }); + const ids = query.getAll('workItemId'); + return HttpResponse.json({ + workItems: ids.length > 0 ? project.cards.filter(card => ids.includes(card.id)) : project.cards, + }); + }), + ); + const record = ({ request }: { request: Request }) => { + // The ambient paged reads ask the stub above what the project holds: the page did not. + if (request.method !== 'GET' || isStubbedProjectRead(request)) return; + const url = new URL(request.url); + if (url.pathname === PHASES_PATH) asked.listings.push(url.searchParams); + if (url.pathname !== CARDS_PATH) return; + if (url.searchParams.has('workItemId')) asked.cardReads.push(url.searchParams.getAll('workItemId')); + else if (url.search === '') asked.wholeBoards += 1; + }; + const countBodies = async ({ request, response }: { request: Request; response: Response }) => { + const { pathname } = new URL(request.url); + if (isStubbedProjectRead(request) || (pathname !== PHASES_PATH && pathname !== CARDS_PATH)) return; + asked.cardsDownloaded += answeredCardsSchema.parse(await response.clone().json()).workItems?.length ?? 0; + }; + server.events.on('request:start', record); + server.events.on('response:mocked', countBodies); + onTestFinished(() => { + server.events.removeListener('request:start', record); + server.events.removeListener('response:mocked', countBodies); + }); + + const boardPath = `/factories/${FACTORY_ID}/work`; + const router = createMemoryRouter(createAppRoutes(), { initialEntries: [`${boardPath}${link}`] }); + const { client } = renderWithProviders(); + /** What a feed frame does to the board. */ + const refresh = () => act(() => client.invalidateQueries({ queryKey: queryKeys.workItems(FACTORY_ID) })); + /** Leaves the link for the board's plain address. */ + const dropLink = () => act(() => router.navigate(boardPath)); + /** Shows the board at another query of its address: another order, search or filter. */ + const show = (query: string) => act(() => router.navigate(`${boardPath}${query}`)); + return { project, asked, refresh, dropLink, show }; +} + +const cardIds = (from: number, to: number) => + Array.from({ length: to - from + 1 }, (_, offset) => largeCardId(from + offset)); + +describe('The board of a large project', () => { + beforeEach(mockBoardRowLayout); + afterEach(() => vi.restoreAllMocks()); + + it('opens on the count of every card of a phase and its first cards only, in one read', async () => { + const { asked } = openLargeBoard(250); + + expect(await screen.findByRole('button', { name: 'Triage, 250' })).toBeInTheDocument(); + expect(await screen.findByRole('button', { name: 'Load more cards' })).toBeInTheDocument(); + expect(screen.getByRole('article', { name: 'Large task 249' })).toBeInTheDocument(); + expect(asked.listings.map(listing => listing.get('cards'))).toEqual(['true']); + expect(asked.cardReads).toEqual([]); + expect(asked.wholeBoards).toBe(0); + }); + + it('lists a phase deeper on demand, and downloads only the cards it does not hold', async () => { + const { asked } = openLargeBoard(250); + const user = userEvent.setup(); + + await user.click(await screen.findByRole('button', { name: 'Load more cards' })); + + await waitFor(() => expect(asked.cardReads).toHaveLength(1)); + // The newest fifty came with the board; the next fifty are the ones to download. + expect(asked.cardReads[0]?.toSorted()).toEqual(cardIds(150, 199)); + expect(asked.listings.at(-1)?.getAll('window')).toEqual(['triage:100']); + expect(asked.listings.at(-1)?.has('cards')).toBe(false); + expect(screen.getByRole('button', { name: 'Triage, 250' })).toBeInTheDocument(); + // The cards just downloaded are the rows the phase now lists below its first fifty. + fireEvent.scroll(boardViewport(), { target: { scrollTop: 60 * 48 } }); + expect(await screen.findByRole('article', { name: 'Large task 189' })).toBeInTheDocument(); + expect(asked.wholeBoards).toBe(0); + }); + + it('lists a second phase deeper while the first one is still being read', async () => { + let answerTriage = () => {}; + const triageHeld = new Promise(resolve => { + answerTriage = resolve; + }); + const { asked } = openLargeBoard(240, index => (index < 120 ? 'triage' : 'planning')); + server.use( + http.get(`${TEST_BASE_URL}${PHASES_PATH}`, async ({ request }) => { + const windows = new URL(request.url).searchParams.getAll('window'); + // Triage's deeper window alone is the read to hold; the ambient read answers every one. + if (windows.length === 1) await triageHeld; + }), + ); + const user = userEvent.setup(); + const [moreOfTriage] = await screen.findAllByRole('button', { name: 'Load more cards' }); + if (!moreOfTriage) throw new Error('Triage offers no more cards'); + + await user.click(moreOfTriage); + await screen.findByRole('status', { name: 'Loading more cards' }); + await user.click(screen.getByRole('button', { name: 'Load more cards' })); + try { + // Planning is asked for while Triage's read is still held. + await waitFor(() => + expect(asked.listings.some(listing => listing.getAll('window').includes('planning:100'))).toBe(true), + ); + } finally { + answerTriage(); + } + + // Each phase listed its newest fifty: the fifty-first of each follows. + await waitFor(() => expect(asked.cardReads).not.toEqual([])); + fireEvent.scroll(boardViewport(), { target: { scrollTop: 50 * 48 } }); + expect(await screen.findByRole('article', { name: 'Large task 69' })).toBeInTheDocument(); + expect(await screen.findByRole('article', { name: 'Large task 189' })).toBeInTheDocument(); + expect(asked.listings.at(-1)?.getAll('window').toSorted()).toEqual(['planning:100', 'triage:100']); + }); + + it('opens a link to the last card of a long phase on that card and the first cards, not the cards above it', async () => { + const linked = largeCardId(0); + const { asked } = openLargeBoard(2000, undefined, `?item=${linked}`); + + expect(await screen.findByRole('article', { name: 'Large task 0' })).toBeInTheDocument(); + expect(screen.getByRole('button', { name: 'Triage, 2000' })).toBeInTheDocument(); + expect(screen.getByRole('article', { name: 'Large task 1999' })).toBeInTheDocument(); + // The phase is not listed down to the card: the rest of it is still to load. + expect(screen.getByRole('button', { name: 'Load more cards' })).toBeInTheDocument(); + expect(asked.listings.map(listing => [listing.get('item'), listing.getAll('window')])).toEqual([[linked, []]]); + expect(asked.cardReads).toEqual([]); + // The newest fifty, and the linked card. + await waitFor(() => expect(asked.cardsDownloaded).toBe(51)); + expect(asked.wholeBoards).toBe(0); + }); + + it('asks for the linked card as long as the address names it, and no longer', async () => { + const linked = largeCardId(0); + const { asked, dropLink } = openLargeBoard(250, undefined, `?item=${linked}`); + expect(await screen.findByRole('article', { name: 'Large task 0' })).toBeInTheDocument(); + + await dropLink(); + + await waitFor(() => expect(screen.queryByRole('article', { name: 'Large task 0' })).not.toBeInTheDocument()); + expect(asked.listings.map(listing => listing.get('item'))).toEqual([linked, null]); + expect(screen.getByRole('article', { name: 'Large task 249' })).toBeInTheDocument(); + expect(asked.cardReads).toEqual([]); + }); + + it('searches the whole project once typing stops, and finds a card it had not loaded', async () => { + const { asked } = openLargeBoard(250); + // No pause between keys: the search settles once, after the last one. + const user = userEvent.setup({ delay: null }); + await screen.findByRole('button', { name: 'Triage, 250' }); + + await user.type(screen.getByRole('searchbox', { name: 'Search cards' }), 'task 137'); + + expect(await screen.findByRole('article', { name: 'Large task 137' })).toBeInTheDocument(); + expect(screen.getByRole('button', { name: 'Triage, 1' })).toBeInTheDocument(); + expect(asked.listings.flatMap(listing => listing.get('q') ?? [])).toEqual(['task 137']); + expect(asked.cardReads).toEqual([[largeCardId(137)]]); + expect(asked.wholeBoards).toBe(0); + }); + + it('downloads nothing on a refresh that changed nothing, and one card when one card changed', async () => { + const { project, asked, refresh } = openLargeBoard(250); + await screen.findByRole('button', { name: 'Load more cards' }); + + await refresh(); + + expect(asked.listings.map(listing => listing.get('cards'))).toEqual(['true', null]); + expect(asked.cardReads).toEqual([]); + expect(screen.getByRole('article', { name: 'Large task 249' })).toBeInTheDocument(); + + project.cards = project.cards.map(card => + card.id === largeCardId(249) + ? { ...card, title: 'Renamed task', workItem: { ...card.workItem, title: 'Renamed task' } } + : card, + ); + await refresh(); + + expect(asked.listings).toHaveLength(3); + expect(asked.cardReads).toEqual([[largeCardId(249)]]); + expect(await screen.findByRole('article', { name: 'Renamed task' })).toBeInTheDocument(); + expect(screen.queryByRole('article', { name: 'Large task 249' })).not.toBeInTheDocument(); + expect(asked.wholeBoards).toBe(0); + }); + + it('offers to read the board again when its read fails, and shows the board once the server answers', async () => { + let down = true; + openLargeBoard(60); + server.use( + http.get(`${TEST_BASE_URL}${PHASES_PATH}`, () => + down ? HttpResponse.json({ error: 'Board unavailable' }, { status: 500 }) : undefined, + ), + ); + const retry = await screen.findByRole('button', { name: 'Retry' }); + expect(screen.getByText('Board unavailable')).toBeInTheDocument(); + + down = false; + await userEvent.click(retry); + + expect(await screen.findByRole('button', { name: 'Triage, 60' })).toBeInTheDocument(); + expect(screen.queryByText('Board unavailable')).not.toBeInTheDocument(); + }); + + it('keeps a card open, with what is typed in it, when the order changes to one the page holds that lists the card deeper', async () => { + const { asked, show } = openLargeBoard(120, undefined, '?sort=created-newest'); + const user = userEvent.setup(); + expect(await screen.findByRole('article', { name: 'Large task 119' })).toBeInTheDocument(); + await show('?sort=created-oldest'); + await user.click(await screen.findByText('Large task 0')); + const panel = await screen.findByRole('dialog', { name: 'Large task 0' }); + await user.click(within(panel).getByRole('button', { name: 'Add a description' })); + await user.type(within(panel).getByRole('textbox', { name: 'Description' }), 'Half a thought'); + + // The newest order is one the page holds, read when no card was open: its fifty cards end far above this one. + await show('?sort=created-newest'); + + expect(await screen.findByRole('article', { name: 'Large task 119' })).toBeInTheDocument(); + await waitFor(() => + expect( + asked.listings + .at(-1) + ?.getAll('sort') + .concat(asked.listings.at(-1)?.getAll('item') ?? []), + ).toEqual(['created-newest', largeCardId(0)]), + ); + expect(screen.getByRole('dialog', { name: 'Large task 0' })).toBe(panel); + expect(within(panel).getByRole('textbox', { name: 'Description' })).toHaveValue('Half a thought'); + }); +}); diff --git a/mastracode/factory-ui/src/ui/__tests__/BoardPagePendingStates.msw.test.tsx b/mastracode/factory-ui/src/ui/__tests__/BoardPagePendingStates.msw.test.tsx index 7e4e1b4902b..596b567d7d7 100644 --- a/mastracode/factory-ui/src/ui/__tests__/BoardPagePendingStates.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/__tests__/BoardPagePendingStates.msw.test.tsx @@ -634,13 +634,11 @@ describe('Board card pending states', () => { it('acknowledges a session start from the card details while it is still resolving the session', async () => { stubBoardEndpoints(); const refreshGate = deferred(); - let workItemRequests = 0; server.use( - http.get(`${TEST_BASE_URL}/web/factory/projects/${FACTORY_ID}/work-items`, async () => { - workItemRequests += 1; - // The start refetches before it can decide to open or create; hold that - // refetch open so the pre-mutation window is observable. - if (workItemRequests > 1) await refreshGate.promise; + http.get(`${TEST_BASE_URL}/web/factory/projects/${FACTORY_ID}/work-items`, async ({ request }) => { + // The start reads the clicked card before it can decide to open or create; hold that + // read open so the pre-mutation window is observable. + if (new URL(request.url).searchParams.has('workItemId')) await refreshGate.promise; return HttpResponse.json({ workItems: [{ ...workItem, sessions: {} }] }); }), http.patch(`${TEST_BASE_URL}/web/factory/work-items/${ITEM_ID}`, async ({ request }) => { @@ -778,12 +776,10 @@ describe('Board card pending states', () => { it('starts one session when the details run control is re-triggered before it resolves', async () => { stubBoardEndpoints(); const refreshGate = deferred(); - let workItemRequests = 0; const runStarts: string[] = []; server.use( - http.get(`${TEST_BASE_URL}/web/factory/projects/${FACTORY_ID}/work-items`, async () => { - workItemRequests += 1; - if (workItemRequests > 1) await refreshGate.promise; + http.get(`${TEST_BASE_URL}/web/factory/projects/${FACTORY_ID}/work-items`, async ({ request }) => { + if (new URL(request.url).searchParams.has('workItemId')) await refreshGate.promise; return HttpResponse.json({ workItems: [{ ...workItem, sessions: {} }] }); }), http.patch(`${TEST_BASE_URL}/web/factory/work-items/${ITEM_ID}`, async ({ request }) => { diff --git a/mastracode/factory-ui/src/ui/__tests__/BoardPageReviewStates.msw.test.tsx b/mastracode/factory-ui/src/ui/__tests__/BoardPageReviewStates.msw.test.tsx index 02f73ee26cd..58281092494 100644 --- a/mastracode/factory-ui/src/ui/__tests__/BoardPageReviewStates.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/__tests__/BoardPageReviewStates.msw.test.tsx @@ -132,7 +132,9 @@ describe('Review card action lifecycle', () => { const { data, transitions, transitionGate, decisionsGate } = stubReviewBoard(candidate); const user = userEvent.setup(); const { client } = renderReviewBoard(); - await user.click(await screen.findByRole('button', { name: 'Review' })); + // The Review column's own header is a button of that name: press the card's. + const card = await screen.findByRole('article', { name: reviewItem.title }); + await user.click(within(card).getByRole('button', { name: 'Review' })); const reviewing = screen.getByRole('region', { name: 'Review' }); await waitFor(() => expect(within(reviewing).getByRole('button', { name: 'Moving…' })).toBeDisabled()); diff --git a/mastracode/factory-ui/src/ui/__tests__/BoardPageSavedViews.msw.test.tsx b/mastracode/factory-ui/src/ui/__tests__/BoardPageSavedViews.msw.test.tsx index 03a7c4c07e1..7e92ba426cf 100644 --- a/mastracode/factory-ui/src/ui/__tests__/BoardPageSavedViews.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/__tests__/BoardPageSavedViews.msw.test.tsx @@ -163,8 +163,9 @@ describe('Factory board saved views', () => { await user.clear(search); await user.type(search, 'Moved'); + // The server searches once typing pauses. + await waitFor(() => expect(within(triage).queryByText('Created later')).not.toBeInTheDocument()); expect(within(triage).queryByText('Moved recently')).not.toBeInTheDocument(); - expect(within(triage).queryByText('Created later')).not.toBeInTheDocument(); await user.keyboard('{Escape}'); expect(search).toHaveValue(''); expect(within(triage).getByText('Created later')).toBeInTheDocument(); @@ -191,13 +192,13 @@ describe('Factory board saved views', () => { await user.click(screen.getByRole('button', { name: 'New view' })); await user.click(screen.getByRole('button', { name: 'Save view' })); await user.type(screen.getByRole('searchbox', { name: 'Search cards' }), 'Created'); - expect(within(triage).queryByText('Moved recently')).not.toBeInTheDocument(); + await waitFor(() => expect(within(triage).queryByText('Moved recently')).not.toBeInTheDocument()); await user.click(screen.getByRole('button', { name: 'All cards' })); expect(screen.getByRole('searchbox', { name: 'Search cards' })).toHaveValue(''); expect(within(triage).getByText('Moved recently')).toBeInTheDocument(); await user.type(screen.getByRole('searchbox', { name: 'Search cards' }), 'missing'); - expect(within(triage).queryByText('Created later')).not.toBeInTheDocument(); + await waitFor(() => expect(within(triage).queryByText('Created later')).not.toBeInTheDocument()); await openPropertiesMenu(user, 'Board properties'); expect(screen.queryByRole('menuitem', { name: 'Save as view' })).not.toBeInTheDocument(); await closePropertiesMenus(user); diff --git a/mastracode/factory-ui/src/ui/__tests__/BoardPageSourceFilters.msw.test.tsx b/mastracode/factory-ui/src/ui/__tests__/BoardPageSourceFilters.msw.test.tsx index b1eccbb6d53..e19aca88ee5 100644 --- a/mastracode/factory-ui/src/ui/__tests__/BoardPageSourceFilters.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/__tests__/BoardPageSourceFilters.msw.test.tsx @@ -73,7 +73,7 @@ function renderBoard(search = '') { return { router, ...renderWithProviders() }; } -function stubHostedSources(issues = hostedIssues) { +function stubHostedSources() { stubSources(); const config: Partial = { github: { enabled: false, sourceIds: [] }, @@ -89,7 +89,7 @@ function stubHostedSources(issues = hostedIssues) { http.get(`${TEST_BASE_URL}/web/intake/config`, () => HttpResponse.json({ config })), http.get(`${TEST_BASE_URL}/web/intake/bindings`, () => HttpResponse.json({ bindings })), http.get(`${TEST_BASE_URL}/web/linear/projects`, () => HttpResponse.json({ projects: hostedProjects })), - http.get(`${TEST_BASE_URL}/web/linear/issues`, () => HttpResponse.json({ issues, nextCursor: null })), + http.get(`${TEST_BASE_URL}/web/linear/issues`, () => HttpResponse.json({ issues: hostedIssues, nextCursor: null })), http.get(`${TEST_BASE_URL}/web/factory/projects/${FACTORY_ID}/work-items`, () => HttpResponse.json({ workItems: hostedCards }), ), @@ -184,7 +184,7 @@ describe('Board source and Linear project filters', () => { const expectDocsWatch = async () => { expect(await screen.findByText('DocsWatch: new documentation request')).toBeInTheDocument(); expect( - within(screen.getByTestId('board-column-planning')).getByText('DocsWatch: legacy planning card'), + within(screen.getByTestId('board-column-planning')).getByText('Portal: workspace settings'), ).toBeInTheDocument(); expect( within(screen.getByTestId('board-column-execute')).getByText('Portal: member permissions'), @@ -204,16 +204,6 @@ describe('Board source and Linear project filters', () => { }); }); - describe('when a hosted issue leaves its project', () => { - it('excludes the stale stored project membership while retaining other matching cards', async () => { - stubHostedSources([...hostedIssues, { ...linearIssue('ENG-104', null), sourceId: hostedTeamId }]); - const view = renderBoard(`?linearProject=${encodeURIComponent(docsWatchId)}`); - await waitForMutationsIdle(view.client); - expect(await screen.findByText('DocsWatch: new documentation request')).toBeInTheDocument(); - expect(screen.queryByText('Portal: member permissions')).not.toBeInTheDocument(); - }); - }); - it('filters live Intake and stored cards across stages, then saves and reloads a project view', async () => { stubSources(); const first = renderBoard(); diff --git a/mastracode/factory-ui/src/ui/__tests__/BoardPageWorkItemActivity.msw.test.tsx b/mastracode/factory-ui/src/ui/__tests__/BoardPageWorkItemActivity.msw.test.tsx index bb15722b219..f39ede6449c 100644 --- a/mastracode/factory-ui/src/ui/__tests__/BoardPageWorkItemActivity.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/__tests__/BoardPageWorkItemActivity.msw.test.tsx @@ -443,9 +443,7 @@ describe('Board work-item activity', () => { }); }), http.get(`${TEST_BASE_URL}/web/factory/projects/${FACTORY_ID}/work-items`, () => - HttpResponse.json({ - workItems: [{ ...linearWorkItem, metadata: { identifier: 'ENG-42' } }], - }), + HttpResponse.json({ workItems: [linearWorkItem] }), ), ); const user = userEvent.setup(); diff --git a/mastracode/factory-ui/src/ui/__tests__/BoardVirtualization.msw.test.tsx b/mastracode/factory-ui/src/ui/__tests__/BoardVirtualization.msw.test.tsx index 377c5fc4b6d..a4f7bd6d235 100644 --- a/mastracode/factory-ui/src/ui/__tests__/BoardVirtualization.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/__tests__/BoardVirtualization.msw.test.tsx @@ -11,17 +11,12 @@ import { queryKeys } from '../../api/keys'; import { createAppRoutes } from '../router'; import type { GithubIssueDetail } from '../domains/factory/services/factory'; import { saveKanbanView } from './boardLayoutQueries'; -import { largeBoard, largeCandidatePage } from './fixtures/largeBoard'; +import { boardViewport, mockBoardRowLayout } from './boardRowLayout'; +import { largeBoard, largeCandidatePage, largeCardId } from './fixtures/largeBoard'; import { FACTORY_ID, stubWorkBoard } from './workBoardStubs'; const ITEM_COUNT = 250; -function viewport() { - const element = screen.getByTestId('board-column-triage').closest('.overflow-auto'); - if (!element) throw new Error('Missing board scroll container'); - return element; -} - function serveWorkItems(count: number) { server.use( http.get(`${TEST_BASE_URL}/web/factory/projects/${FACTORY_ID}/work-items`, () => @@ -45,21 +40,7 @@ function renderBoard(search = '', itemCount = ITEM_COUNT) { } describe('Large factory boards', () => { - beforeEach(() => { - const height = function (this: Element) { - return this.matches('.overflow-auto') ? 600 : 48; - }; - vi.spyOn(HTMLElement.prototype, 'offsetHeight', 'get').mockImplementation(height); - vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(1200); - // TanStack Virtual sizes the scroll viewport from its client box. - vi.spyOn(Element.prototype, 'clientHeight', 'get').mockImplementation(height); - vi.spyOn(Element.prototype, 'clientWidth', 'get').mockReturnValue(1200); - vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(function (this: Element) { - const scroller = this.closest('.overflow-auto'); - const height = this.matches('.overflow-auto') ? 600 : 48; - return new DOMRect(0, this === scroller ? 0 : -(scroller?.scrollTop ?? 0), 1200, height); - }); - }); + beforeEach(mockBoardRowLayout); afterEach(() => vi.restoreAllMocks()); it.each(['list', 'board'] as const)( @@ -70,18 +51,18 @@ describe('Large factory boards', () => { if (layout === 'board') await saveKanbanView(userEvent.setup()); expect(screen.getAllByTestId('work-item-card').length).toBeLessThan(35); - fireEvent.scroll(viewport(), { target: { scrollTop: 6000 } }); + fireEvent.scroll(boardViewport(), { target: { scrollTop: 6000 } }); await waitFor(() => expect(screen.queryByLabelText('Large task 249')).not.toBeInTheDocument()); expect(screen.getAllByTestId('work-item-card').length).toBeLessThan(35); - fireEvent.scroll(viewport(), { target: { scrollTop: 0 } }); + fireEvent.scroll(boardViewport(), { target: { scrollTop: 0 } }); expect(await screen.findByLabelText('Large task 249')).toBeInTheDocument(); expect(screen.getAllByTestId('work-item-card').length).toBeLessThan(35); }, ); it('given a deep link to the last issue, shows and focuses it without mounting all preceding issues', async () => { - renderBoard('?item=large-0'); + renderBoard(`?item=${largeCardId(0)}`); expect(await screen.findByLabelText('Large task 0')).toBeInTheDocument(); expect(screen.getByRole('button', { name: 'Details for Large task 0' })).toHaveFocus(); expect(screen.getAllByTestId('work-item-card').length).toBeLessThan(35); @@ -93,27 +74,27 @@ describe('Large factory boards', () => { onTestFinished(() => { Reflect.deleteProperty(Element.prototype, 'scrollIntoView'); }); - const { router } = renderBoard('?item=large-100'); + const { router } = renderBoard(`?item=${largeCardId(100)}`); await waitFor(() => expect(screen.getByRole('button', { name: 'Details for Large task 100' })).toHaveFocus()); expect(scrollIntoView).toHaveBeenCalledTimes(1); - fireEvent.scroll(viewport(), { target: { scrollTop: 0 } }); - const scrollTo = vi.spyOn(viewport(), 'scrollTo'); - await act(() => router.navigate(`/factories/${FACTORY_ID}/work?item=large-100&sort=created-oldest`)); + fireEvent.scroll(boardViewport(), { target: { scrollTop: 0 } }); + const scrollTo = vi.spyOn(boardViewport(), 'scrollTo'); + await act(() => router.navigate(`/factories/${FACTORY_ID}/work?item=${largeCardId(100)}&sort=created-oldest`)); expect(await screen.findByLabelText('Large task 0')).toBeInTheDocument(); expect(scrollTo).not.toHaveBeenCalled(); expect(scrollIntoView).toHaveBeenCalledTimes(1); - expect(viewport().scrollTop).toBe(0); + expect(boardViewport().scrollTop).toBe(0); }); - it('given an offscreen issue, finds it by searching the full dataset', async () => { + it('given an issue the board has not loaded, finds it by searching the full dataset', async () => { const { router } = renderBoard(); await screen.findByLabelText('Large task 249'); - expect(screen.queryByLabelText('Large task 0')).not.toBeInTheDocument(); - await act(() => router.navigate(`/factories/${FACTORY_ID}/work?search=Large+task+0`)); - expect(await screen.findByLabelText('Large task 0')).toBeInTheDocument(); - expect(screen.getAllByTestId('work-item-card')).toHaveLength(1); + expect(screen.queryByLabelText('Large task 137')).not.toBeInTheDocument(); + await act(() => router.navigate(`/factories/${FACTORY_ID}/work?search=task+137`)); + expect(await screen.findByLabelText('Large task 137')).toBeInTheDocument(); + await waitFor(() => expect(screen.getAllByTestId('work-item-card')).toHaveLength(1)); }); it('given open details, scrolling keeps the card and its description draft alive', async () => { @@ -125,7 +106,7 @@ describe('Large factory boards', () => { const draft = within(details).getByRole('textbox', { name: 'Description' }); await user.type(draft, 'Keep this draft while I scroll'); - fireEvent.scroll(viewport(), { target: { scrollTop: 6000 } }); + fireEvent.scroll(boardViewport(), { target: { scrollTop: 6000 } }); await waitFor(() => expect(screen.queryByRole('article', { name: 'Large task 248' })).not.toBeInTheDocument()); expect(details).toBeInTheDocument(); expect(draft).toHaveValue('Keep this draft while I scroll'); @@ -176,7 +157,7 @@ describe('Large factory boards', () => { const details = await screen.findByRole('button', { name: 'Details for Large task 249' }); act(() => details.focus()); - fireEvent.scroll(viewport(), { target: { scrollTop: 6000 } }); + fireEvent.scroll(boardViewport(), { target: { scrollTop: 6000 } }); await waitFor(() => expect(screen.queryByLabelText('Large task 248')).not.toBeInTheDocument()); expect(details).toHaveFocus(); @@ -191,7 +172,7 @@ describe('Large factory boards', () => { const dataTransfer = { setData: (type: string, value: string) => transferred.set(type, value) }; fireEvent.dragStart(card, { dataTransfer }); - fireEvent.scroll(viewport(), { target: { scrollTop: 6000 } }); + fireEvent.scroll(boardViewport(), { target: { scrollTop: 6000 } }); await waitFor(() => expect(screen.queryByLabelText('Large task 248')).not.toBeInTheDocument()); expect(card).toBeInTheDocument(); @@ -252,7 +233,7 @@ describe('Large factory boards', () => { expect(prompt).toHaveFocus(); expect(screen.getAllByTestId('candidate-card').length).toBeLessThan(35); expect(screen.queryByRole('button', { name: 'Load more candidates' })).not.toBeInTheDocument(); - fireEvent.scroll(viewport(), { target: { scrollTop: 6000 } }); + fireEvent.scroll(boardViewport(), { target: { scrollTop: 6000 } }); await waitFor(() => expect(screen.queryByRole('article', { name: 'Candidate 1' })).not.toBeInTheDocument()); expect(prompt).toHaveValue('Keep this guidance while loading more'); expect(screen.getAllByTestId('candidate-card').length).toBeLessThan(35); @@ -285,7 +266,7 @@ describe('Large factory boards', () => { if (layout === 'board') await saveKanbanView(userEvent.setup()); expect(screen.getAllByTestId('candidate-card').length).toBeLessThan(35); - fireEvent.scroll(viewport(), { target: { scrollTop: 6000 } }); + fireEvent.scroll(boardViewport(), { target: { scrollTop: 6000 } }); await waitFor(() => expect(screen.queryByRole('article', { name: 'Candidate 0' })).not.toBeInTheDocument()); expect(screen.getAllByTestId('candidate-card').length).toBeLessThan(35); }, diff --git a/mastracode/factory-ui/src/ui/__tests__/boardRowLayout.ts b/mastracode/factory-ui/src/ui/__tests__/boardRowLayout.ts new file mode 100644 index 00000000000..9a8051b3b26 --- /dev/null +++ b/mastracode/factory-ui/src/ui/__tests__/boardRowLayout.ts @@ -0,0 +1,29 @@ +import { screen } from '@testing-library/react'; +import { vi } from 'vitest'; + +/** + * Gives jsdom, which lays nothing out, the boxes a board's virtual window measures: a 600px scroll + * viewport over 48px rows. `vi.restoreAllMocks()` takes them back. + */ +export function mockBoardRowLayout() { + const height = function (this: Element) { + return this.matches('.overflow-auto') ? 600 : 48; + }; + vi.spyOn(HTMLElement.prototype, 'offsetHeight', 'get').mockImplementation(height); + vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(1200); + // TanStack Virtual sizes the scroll viewport from its client box. + vi.spyOn(Element.prototype, 'clientHeight', 'get').mockImplementation(height); + vi.spyOn(Element.prototype, 'clientWidth', 'get').mockReturnValue(1200); + vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(function (this: Element) { + const scroller = this.closest('.overflow-auto'); + const height = this.matches('.overflow-auto') ? 600 : 48; + return new DOMRect(0, this === scroller ? 0 : -(scroller?.scrollTop ?? 0), 1200, height); + }); +} + +/** The element the board scrolls in. */ +export function boardViewport() { + const element = screen.getByTestId('board-column-triage').closest('.overflow-auto'); + if (!element) throw new Error('Missing board scroll container'); + return element; +} diff --git a/mastracode/factory-ui/src/ui/__tests__/fixtures/boardSourceFilters.ts b/mastracode/factory-ui/src/ui/__tests__/fixtures/boardSourceFilters.ts index b8af8e04df9..e3959ee25d1 100644 --- a/mastracode/factory-ui/src/ui/__tests__/fixtures/boardSourceFilters.ts +++ b/mastracode/factory-ui/src/ui/__tests__/fixtures/boardSourceFilters.ts @@ -32,7 +32,7 @@ export function linearIssue(identifier: string, projectId: string | null, title export const linearIssues: LinearIssue[] = [ linearIssue('ENG-101', 'project-a', 'Portal: add account switcher'), linearIssue('ENG-201', 'project-b', 'Billing: export invoices'), - // This filed card moved to Billing; its live metadata must override the older stored project. + // Already filed: the board shows its card, in the project the server last synced it to. linearIssue('ENG-301', 'project-b', 'Move to Billing'), linearIssue('ENG-401', null, 'Unassigned project'), ]; @@ -67,7 +67,7 @@ export const sourceCards: WorkItem[] = [ card('ENG-103', 'Portal: workspace settings', 'linear-issue', 'planning', 'project-a'), card('ENG-104', 'Portal: member permissions', 'linear-issue', 'execute', 'project-a'), card('ENG-202', 'Billing: payment history', 'linear-issue', 'planning', 'project-b'), - card('ENG-301', 'Moved project card', 'linear-issue', 'planning', 'project-a'), + card('ENG-301', 'Moved project card', 'linear-issue', 'planning', 'project-b'), card('50', 'GitHub: update dependencies', 'github-issue', 'planning'), card('manual', 'Manual follow-up', 'manual', 'intake'), ]; diff --git a/mastracode/factory-ui/src/ui/__tests__/fixtures/hostedLinearProjectFilters.ts b/mastracode/factory-ui/src/ui/__tests__/fixtures/hostedLinearProjectFilters.ts index 0917a63a440..3c865b8a13b 100644 --- a/mastracode/factory-ui/src/ui/__tests__/fixtures/hostedLinearProjectFilters.ts +++ b/mastracode/factory-ui/src/ui/__tests__/fixtures/hostedLinearProjectFilters.ts @@ -15,8 +15,8 @@ export const hostedProjects: LinearProject[] = [ export const hostedIssues: LinearIssue[] = [ linearIssue('ENG-101', docsWatchId, 'DocsWatch: new documentation request'), - // A card filed before project metadata was available must use its live issue. - linearIssue('ENG-103', docsWatchId, 'DocsWatch: legacy planning card'), + // Already filed: the board shows its card, not the issue. + linearIssue('ENG-103', docsWatchId, 'DocsWatch: filed planning issue'), linearIssue('ENG-301', otherWorkspaceProjectId, 'Other workspace card'), linearIssue('ENG-401', null, 'Unassigned project'), ].map(issue => ({ @@ -31,8 +31,6 @@ export const hostedCards = wireSourceCards.map(item => { title: 'Other workspace card', metadata: { ...item.metadata, linearProjectId: otherWorkspaceProjectId }, }; - if (item.id === 'ENG-103') - return { ...item, title: 'DocsWatch: legacy planning card', metadata: { labels: ['feature'] } }; if (item.metadata.linearProjectId !== 'project-a') return item; return { ...item, metadata: { ...item.metadata, linearProjectId: docsWatchId } }; }); diff --git a/mastracode/factory-ui/src/ui/__tests__/fixtures/largeBoard.ts b/mastracode/factory-ui/src/ui/__tests__/fixtures/largeBoard.ts index b554f31fc09..a6a717315d5 100644 --- a/mastracode/factory-ui/src/ui/__tests__/fixtures/largeBoard.ts +++ b/mastracode/factory-ui/src/ui/__tests__/fixtures/largeBoard.ts @@ -1,6 +1,11 @@ import type { Card } from '@mastra/factory'; import type { GithubIssuePage } from '../../domains/factory/services/factory'; +/** The id of the card titled `Large task `. */ +export function largeCardId(index: number): string { + return `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`; +} + export function largeBoard(count: number, factoryProjectId = 'fp-1'): Card[] { return Array.from({ length: count }, (_, index) => ({ workItemId: `work-large-${index}`, @@ -25,7 +30,7 @@ export function largeBoard(count: number, factoryProjectId = 'fp-1'): Card[] { createdAt: new Date(Date.UTC(2026, 6, 18, 0, index)), updatedAt: new Date(Date.UTC(2026, 6, 18, 0, index)), }, - id: `large-${index}`, + id: largeCardId(index), orgId: 'org-1', createdBy: 'user-1', factoryProjectId, diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardCandidates.test.ts b/mastracode/factory-ui/src/ui/domains/factory/boardCandidates.test.ts index a990fe927cb..cc2d3f59740 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardCandidates.test.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardCandidates.test.ts @@ -3,7 +3,18 @@ import { describe, expect, it } from 'vitest'; import type { IncidentioIssue } from './services/incidentio'; import type { JiraIssue } from './services/jira'; import type { LinearIssue } from './services/linear'; -import { incidentioCandidate, jiraCandidate, linearCandidate } from './boardCandidates'; +import { searchWords } from '@mastra/factory/work-items/search-words'; + +import { boardFiltersFromParams } from './boardFilters'; +import { + candidateMatchesView, + incidentioCandidate, + issueCandidate, + jiraCandidate, + linearCandidate, + pullRequestCandidate, +} from './boardCandidates'; +import type { BoardCandidate } from './boardCandidates'; const issue: JiraIssue = { id: 'jira-issue:encoded-reference', @@ -112,3 +123,79 @@ describe('jiraCandidate', () => { }); }); }); + +describe('candidateMatchesView', () => { + const githubIssue = issueCandidate({ + number: 7, + title: 'Fix login bug', + url: 'https://github.com/acme/app/issues/7', + author: 'octocat', + assignee: 'hubot', + assignees: ['hubot', 'monalisa'], + labels: ['bug', 'p1'], + comments: 0, + createdAt: '2026-08-01T09:00:00.000Z', + updatedAt: '2026-08-01T09:00:00.000Z', + }); + const githubPr = pullRequestCandidate({ + number: 12, + title: 'Ship relevance filters', + url: 'https://github.com/acme/app/pull/12', + author: 'octocat', + assignees: ['hubot'], + requestedReviewers: ['monalisa'], + baseBranch: 'main', + headBranch: 'feat/relevance', + createdAt: '2026-08-01T09:00:00.000Z', + updatedAt: '2026-08-01T09:00:00.000Z', + }); + const jira = jiraCandidate(issue); + const incident = incidentioCandidate(followUp); + + const matches = (candidate: BoardCandidate, query: string, search = '') => + candidateMatchesView(candidate, boardFiltersFromParams(new URLSearchParams(query), true), searchWords(search)); + + it('keeps every issue when the view picks nothing and searches nothing', () => { + expect(matches(githubIssue, '')).toBe(true); + }); + + it('matches each person filter only through its own role, and Involves through any', () => { + expect(matches(githubIssue, 'assignee=github%3Ahubot')).toBe(true); + expect(matches(githubIssue, 'assignee=github%3Amonalisa')).toBe(true); + expect(matches(githubIssue, 'author=github%3Ahubot')).toBe(false); + expect(matches(githubIssue, 'teammate=github%3Ahubot')).toBe(true); + expect(matches(githubPr, 'reviewer=github%3Amonalisa')).toBe(true); + expect(matches(githubPr, 'reviewer=github%3Ahubot')).toBe(false); + expect(matches(jira, 'author=jira%3Agrace')).toBe(true); + expect(matches(jira, 'assignee=jira%3Aada')).toBe(true); + expect(matches(incident, 'assignee=incidentio%3Agrace%20hopper')).toBe(true); + }); + + it('never matches Worked on: nobody has worked on an issue that is not filed', () => { + expect(matches(githubIssue, 'worked=github%3Aoctocat')).toBe(false); + }); + + it('matches the signed-in user by any id the stored filter names them with', () => { + expect(matches(githubIssue, 'author=factory%3Auser-octo&author=github%3Aoctocat')).toBe(true); + expect(matches(githubIssue, 'author=factory%3Auser-octo')).toBe(false); + }); + + it('requires every picked label', () => { + expect(matches(githubIssue, 'label=bug&label=p1')).toBe(true); + expect(matches(githubIssue, 'label=bug&label=missing')).toBe(false); + }); + + it('narrows by provider, and lists pull requests under their own source', () => { + expect(matches(githubIssue, 'source=github')).toBe(true); + expect(matches(jira, 'source=github')).toBe(false); + expect(matches(githubPr, 'source=pull-request')).toBe(true); + expect(matches(githubIssue, 'source=pull-request')).toBe(false); + }); + + it('finds an issue by every searched word, in its title or its key, whatever their order and case', () => { + expect(matches(githubIssue, '', 'BUG fix')).toBe(true); + expect(matches(githubIssue, '', 'fix cache')).toBe(false); + expect(matches(githubIssue, '', '#7')).toBe(true); + expect(matches(jira, '', 'eng-42 intake')).toBe(true); + }); +}); diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardCandidates.ts b/mastracode/factory-ui/src/ui/domains/factory/boardCandidates.ts index 2640f32d34b..82f5a54bfee 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardCandidates.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardCandidates.ts @@ -1,15 +1,27 @@ import { AUTO_TRIAGED_LABEL } from '@mastra/factory/rules/types'; +import { hasEveryLabel, metadataLabels } from '@mastra/factory/work-items/card-labels'; +import { matchesPeople, providerPeople } from '@mastra/factory/work-items/card-people'; +import type { ProviderPerson } from '@mastra/factory/work-items/card-people'; +import { matchesSourceFilters } from '@mastra/factory/work-items/card-source-filters'; +import { hasEveryWord } from '@mastra/factory/work-items/search-words'; import { relativeTime } from '../../../lib/date/relativeTime'; -import { githubSourceKey, hasLabel } from './boardItems'; -import { itemAppearsInStage } from './boardStages'; +import type { BoardFilterState } from './boardFilters'; +import { githubSourceKey, hasLabel, workItemKey } from './boardItems'; import type { GithubIssue, GithubPullRequest } from './services/factory'; import type { GitLabIssue, GitLabMergeRequest } from './services/gitlab'; import type { IncidentioIssue } from './services/incidentio'; import type { JiraIssue } from './services/jira'; import type { LinearIssue } from './services/linear'; -import type { WorkItem, WorkItemSource } from './services/workItems'; +import { isPullRequestSource } from './services/workItems'; +import type { WorkItemSource } from './services/workItems'; import type { BoardStageId } from './stages'; +const NOBODY: ReadonlySet = new Set(); + +function participantIds(people: readonly ProviderPerson[]): ReadonlySet { + return new Set(people.map(person => person.id)); +} + export type IntakeSource = 'github' | 'github-prs' | 'gitlab-prs' | 'gitlab' | 'linear' | 'jira' | 'incidentio'; /** What a candidate feed exposes to the column rendering it. */ @@ -195,15 +207,26 @@ export function incidentioCandidate(issue: IncidentioIssue): BoardCandidate { }; } -export function stageContentCount( - stage: BoardStageId, - stages: ReadonlyArray<{ id: BoardStageId }>, - workItems: readonly WorkItem[], - candidates: readonly BoardCandidate[], -): number { - let count = candidates.filter(candidate => candidate.column === stage).length; - for (const item of workItems) { - if (itemAppearsInStage(item, stage, stages)) count += 1; - } - return count; +/** + * Whether a board view keeps an issue not filed yet, by the rules the server lists cards with. + * `filters` names people by every id they go by, as the server is asked. + */ +export function candidateMatchesView( + candidate: BoardCandidate, + filters: BoardFilterState, + words: readonly string[], +): boolean { + const people = providerPeople(candidate); + const relations = { + worked: NOBODY, + authored: participantIds(people.authored), + assigned: participantIds(people.assigned), + 'review-requested': participantIds(people['review-requested']), + }; + return ( + matchesPeople(relations, filters) && + hasEveryLabel(new Set(metadataLabels(candidate.metadata)), filters.label) && + matchesSourceFilters({ ...candidate, hasPullRequest: isPullRequestSource(candidate.source) }, filters) && + hasEveryWord(`${candidate.title} ${workItemKey(candidate) ?? ''}`.toLowerCase(), words) + ); } diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardFilters.ts b/mastracode/factory-ui/src/ui/domains/factory/boardFilters.ts index bba456bd1c7..d05ad91f552 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardFilters.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardFilters.ts @@ -1,7 +1,6 @@ +import { BOARD_PERSON_FIELDS } from '@mastra/factory/work-items/card-people'; import type { FilterBarItem } from '@mastra/playground-ui/components/FilterBar'; -import { BOARD_PERSON_FIELDS } from './boardPeople'; - /** Every board filter, in menu order. Each id is also its query parameter and its saved-view item's `fieldId`. */ export const BOARD_FILTER_FIELDS = ['source', 'linearProject', ...BOARD_PERSON_FIELDS, 'label'] as const; export type BoardFilterFieldId = (typeof BOARD_FILTER_FIELDS)[number]; diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardItems.ts b/mastracode/factory-ui/src/ui/domains/factory/boardItems.ts index bed6b6e0091..5026eb65f86 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardItems.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardItems.ts @@ -36,11 +36,6 @@ export function sourceMetadata(item: Pick): R }; } -export function metadataLabels(metadata: Record): string[] { - if (!Array.isArray(metadata.labels)) return []; - return metadata.labels.filter((label): label is string => typeof label === 'string'); -} - export function metadataLabelColors(metadata: Record): Record { if (!metadata.labelColors || typeof metadata.labelColors !== 'object' || Array.isArray(metadata.labelColors)) return {}; @@ -228,16 +223,6 @@ export function workItemMeta(item: WorkItem): readonly string[] { return [key, ...(owner ? [owner] : []), age]; } -/** Free-text card match over what names it on the board: its title and its issue key. */ -export function cardMatchesSearch( - card: Pick, - query: string, -): boolean { - const needle = query.trim().toLowerCase(); - if (needle === '') return true; - return [card.title, workItemKey(card) ?? ''].some(text => text.toLowerCase().includes(needle)); -} - /** * Branch + thread title for a card's session, shared with the server's runs * (`workItemBranch`), so the title click and a later run converge on one diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardLabels.test.ts b/mastracode/factory-ui/src/ui/domains/factory/boardLabels.test.ts index 65669109687..edfec14f8fa 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardLabels.test.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardLabels.test.ts @@ -1,46 +1,11 @@ import { describe, expect, it } from 'vitest'; import { issueCandidate, linearCandidate } from './boardCandidates'; -import { boardLabels, candidateMatchesLabels, workItemMatchesLabels } from './boardLabels'; -import type { WorkItem } from './services/workItems'; - -const item: WorkItem = { - id: 'item-1', - orgId: 'org-1', - createdBy: 'factory-rule-dispatcher', - githubProjectId: 'factory-1', - source: 'github-pr', - sourceKey: 'github-pr:12', - parentWorkItemId: null, - title: 'Ship relevance filters', - url: 'https://github.com/acme/app/pull/12', - stages: ['review'], - stageHistory: [], - sessions: { - review: { - sessionId: 'session-1', - threadId: 'thread-1', - branch: 'review/relevance', - startedBy: 'user-grace', - }, - }, - metadata: { - author: 'octocat', - assignees: ['hubot'], - requestedReviewers: ['monalisa'], - }, - triageType: null, - acceptedAt: null, - description: null, - revision: 1, - createdAt: '2026-08-01T09:00:00.000Z', - updatedAt: '2026-08-05T09:00:00.000Z', -}; +import { boardLabels } from './boardLabels'; describe('board labels', () => { - it('collects labels across items and candidates and keeps only cards carrying every picked label', () => { - const labelled: WorkItem = { ...item, metadata: { ...item.metadata, labels: ['bug', 'p1'] } }; - const candidate = issueCandidate({ + it("offers the labels of the project's cards and of issues not filed yet, each once, in alphabetical order", () => { + const github = issueCandidate({ number: 8, title: 'Fix cache', url: 'https://github.com/acme/app/issues/8', @@ -51,7 +16,6 @@ describe('board labels', () => { createdAt: '2026-08-01T09:00:00.000Z', updatedAt: '2026-08-01T09:00:00.000Z', }); - const linear = linearCandidate({ id: 'linear-2', identifier: 'ENG-13', @@ -68,34 +32,11 @@ describe('board labels', () => { updatedAt: '2026-08-01T09:00:00.000Z', }); - expect(boardLabels({ items: [labelled], candidates: [candidate, linear] })).toEqual([ + expect(boardLabels({ labels: ['p1', 'bug'], candidates: [github, linear] })).toEqual([ 'bug', 'frontend', 'p1', 'ux', ]); - expect(candidateMatchesLabels(linear, new Set(['frontend']))).toBe(true); - expect(workItemMatchesLabels(labelled, new Set())).toBe(true); - expect(workItemMatchesLabels(labelled, new Set(['bug', 'p1']))).toBe(true); - expect(workItemMatchesLabels(labelled, new Set(['bug', 'missing']))).toBe(false); - expect(candidateMatchesLabels(candidate, new Set(['p1']))).toBe(true); - expect(candidateMatchesLabels(candidate, new Set(['bug']))).toBe(false); - }); - - it('matches labels the live candidate gained since the item was stored', () => { - const live = issueCandidate({ - number: 12, - title: 'Ship relevance filters', - url: 'https://github.com/acme/app/issues/12', - author: 'octocat', - assignee: null, - labels: ['bug'], - comments: 0, - createdAt: '2026-08-01T09:00:00.000Z', - updatedAt: '2026-08-02T09:00:00.000Z', - }); - - expect(workItemMatchesLabels(item, new Set(['bug']))).toBe(false); - expect(workItemMatchesLabels(item, new Set(['bug']), live)).toBe(true); }); }); diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardLabels.ts b/mastracode/factory-ui/src/ui/domains/factory/boardLabels.ts index c3b1b5a2c73..44c1469d69b 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardLabels.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardLabels.ts @@ -1,33 +1,17 @@ -import type { BoardCandidate } from './boardCandidates'; -import { metadataLabels, sourceMetadata } from './boardItems'; -import type { WorkItem } from './services/workItems'; +import { metadataLabels } from '@mastra/factory/work-items/card-labels'; +import type { BoardCandidate } from './boardCandidates'; + +/** The labels the label filter offers: the ones the project's cards carry, and the ones of issues not filed yet. */ export function boardLabels({ - items, + labels: filed, candidates, }: { - items: readonly WorkItem[]; + /** The labels of the project's cards, as the server lists them. */ + labels: readonly string[]; candidates: readonly BoardCandidate[]; }): string[] { - const labels = new Set(); - for (const card of [...items, ...candidates]) - for (const label of metadataLabels(sourceMetadata(card))) labels.add(label); + const labels = new Set(filed); + for (const candidate of candidates) for (const label of metadataLabels(candidate.metadata)) labels.add(label); return [...labels].sort((left, right) => left.localeCompare(right)); } - -export function workItemMatchesLabels( - item: WorkItem, - selectedLabels: ReadonlySet, - liveCandidate?: BoardCandidate, -): boolean { - if (selectedLabels.size === 0) return true; - const itemLabels = new Set(metadataLabels(sourceMetadata(item))); - if (liveCandidate) for (const label of metadataLabels(liveCandidate.metadata)) itemLabels.add(label); - return [...selectedLabels].every(label => itemLabels.has(label)); -} - -export function candidateMatchesLabels(candidate: BoardCandidate, selectedLabels: ReadonlySet): boolean { - if (selectedLabels.size === 0) return true; - const labels = new Set(metadataLabels(candidate.metadata)); - return [...selectedLabels].every(label => labels.has(label)); -} diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardOrder.test.ts b/mastracode/factory-ui/src/ui/domains/factory/boardOrder.test.ts deleted file mode 100644 index 4b4082aba68..00000000000 --- a/mastracode/factory-ui/src/ui/domains/factory/boardOrder.test.ts +++ /dev/null @@ -1,115 +0,0 @@ -import { describe, expect, it } from 'vitest'; - -import { orderWorkItemsForStage } from './boardOrder'; -import type { WorkItem, WorkItemStageEntry } from './services/workItems'; - -function item({ - id, - createdAt, - updatedAt = createdAt, - stageHistory = [], -}: { - id: string; - createdAt: string; - updatedAt?: string; - stageHistory?: WorkItemStageEntry[]; -}): WorkItem { - return { - id, - orgId: 'org-1', - createdBy: 'user-1', - githubProjectId: 'factory-1', - source: 'manual', - sourceKey: null, - parentWorkItemId: null, - title: id, - url: null, - stages: ['triage'], - stageHistory, - sessions: {}, - metadata: {}, - triageType: null, - acceptedAt: null, - description: null, - revision: 1, - createdAt, - updatedAt, - }; -} - -describe('board column order', () => { - it('places the card most recently entered into the column first', () => { - const olderCardMovedRecently = item({ - id: 'older-card', - createdAt: '2026-07-20T09:00:00.000Z', - stageHistory: [{ stage: 'triage', enteredAt: '2026-07-23T11:00:00.000Z', by: 'user-1' }], - }); - const newerCardMovedEarlier = item({ - id: 'newer-card', - createdAt: '2026-07-22T09:00:00.000Z', - stageHistory: [{ stage: 'triage', enteredAt: '2026-07-23T10:00:00.000Z', by: 'user-2' }], - }); - - expect( - orderWorkItemsForStage([newerCardMovedEarlier, olderCardMovedRecently], 'triage').map(card => card.id), - ).toEqual(['older-card', 'newer-card']); - }); - - it('does not move a card when an unrelated write changes updatedAt', () => { - const recentlyPositioned = item({ - id: 'recently-positioned', - createdAt: '2026-07-20T09:00:00.000Z', - updatedAt: '2026-07-23T11:00:00.000Z', - stageHistory: [{ stage: 'triage', enteredAt: '2026-07-23T10:00:00.000Z', by: 'user-1' }], - }); - const recentlyWritten = item({ - id: 'recently-written', - createdAt: '2026-07-21T09:00:00.000Z', - updatedAt: '2026-07-24T12:00:00.000Z', - stageHistory: [{ stage: 'triage', enteredAt: '2026-07-22T10:00:00.000Z', by: 'user-2' }], - }); - - expect(orderWorkItemsForStage([recentlyWritten, recentlyPositioned], 'triage').map(card => card.id)).toEqual([ - 'recently-positioned', - 'recently-written', - ]); - }); - - it('falls back to creation time for cards without a matching stage entry', () => { - const oldest = item({ id: 'oldest', createdAt: '2026-07-20T09:00:00.000Z' }); - const newest = item({ id: 'newest', createdAt: '2026-07-22T09:00:00.000Z' }); - - expect(orderWorkItemsForStage([oldest, newest], 'triage').map(card => card.id)).toEqual(['newest', 'oldest']); - }); - - it('can prioritize cards the current user most recently moved into the column', () => { - const movedByMe = item({ - id: 'moved-by-me', - createdAt: '2026-07-20T09:00:00.000Z', - stageHistory: [{ stage: 'triage', enteredAt: '2026-07-22T10:00:00.000Z', by: 'user-1' }], - }); - const movedByTeammate = item({ - id: 'moved-by-teammate', - createdAt: '2026-07-21T09:00:00.000Z', - stageHistory: [{ stage: 'triage', enteredAt: '2026-07-24T10:00:00.000Z', by: 'user-2' }], - }); - - expect( - orderWorkItemsForStage([movedByTeammate, movedByMe], 'triage', 'recent-mine', 'user-1').map(card => card.id), - ).toEqual(['moved-by-me', 'moved-by-teammate']); - }); - - it('can sort by Factory creation time in either direction', () => { - const oldest = item({ id: 'oldest', createdAt: '2026-07-20T09:00:00.000Z' }); - const newest = item({ id: 'newest', createdAt: '2026-07-22T09:00:00.000Z' }); - - expect(orderWorkItemsForStage([oldest, newest], 'triage', 'created-newest').map(card => card.id)).toEqual([ - 'newest', - 'oldest', - ]); - expect(orderWorkItemsForStage([oldest, newest], 'triage', 'created-oldest').map(card => card.id)).toEqual([ - 'oldest', - 'newest', - ]); - }); -}); diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardOrder.ts b/mastracode/factory-ui/src/ui/domains/factory/boardOrder.ts deleted file mode 100644 index 41d944fd614..00000000000 --- a/mastracode/factory-ui/src/ui/domains/factory/boardOrder.ts +++ /dev/null @@ -1,41 +0,0 @@ -import type { WorkItem, WorkItemStageEntry } from './services/workItems'; -import type { BoardStageId } from './stages'; - -export const BOARD_SORTS = ['recent', 'recent-mine', 'created-newest', 'created-oldest'] as const; -export type BoardSort = (typeof BOARD_SORTS)[number]; - -function latestColumnEntry(item: WorkItem, stage: BoardStageId): WorkItemStageEntry | undefined { - let latest: WorkItemStageEntry | undefined; - for (const entry of item.stageHistory) { - if (entry.stage !== stage || (latest !== undefined && entry.enteredAt <= latest.enteredAt)) continue; - latest = entry; - } - return latest; -} - -function columnPositionAt(item: WorkItem, stage: BoardStageId): string { - return latestColumnEntry(item, stage)?.enteredAt ?? item.createdAt; -} - -/** Orders persisted cards using Factory-owned timestamps; provider update clocks never participate. */ -export function orderWorkItemsForStage( - items: readonly WorkItem[], - stage: BoardStageId, - sort: BoardSort = 'recent', - currentUserId?: string, -): WorkItem[] { - return items.toSorted((left, right) => { - if (sort === 'recent-mine' && currentUserId) { - const leftMine = latestColumnEntry(left, stage)?.by === currentUserId; - const rightMine = latestColumnEntry(right, stage)?.by === currentUserId; - if (leftMine !== rightMine) return rightMine ? 1 : -1; - } - if (sort === 'created-newest' || sort === 'created-oldest') { - const direction = sort === 'created-newest' ? -1 : 1; - return left.createdAt.localeCompare(right.createdAt) * direction || right.id.localeCompare(left.id); - } - return ( - columnPositionAt(right, stage).localeCompare(columnPositionAt(left, stage)) || right.id.localeCompare(left.id) - ); - }); -} diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardPeople.test.ts b/mastracode/factory-ui/src/ui/domains/factory/boardPeople.test.ts index 4c5df9c48a6..b526ee0d25b 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardPeople.test.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardPeople.test.ts @@ -1,76 +1,26 @@ import { describe, expect, it } from 'vitest'; -import { - gitlabCandidate, - incidentioCandidate, - issueCandidate, - jiraCandidate, - linearCandidate, - pullRequestCandidate, -} from './boardCandidates'; +import { issueCandidate } from './boardCandidates'; import { boardFiltersFromParams } from './boardFilters'; -import { - boardParticipants, - boardPersonIdentity, - candidateMatchesPeople, - withPeopleFolded, - withPeopleUnfolded, - workItemMatchesPeople, -} from './boardPeople'; +import { boardParticipants, boardPersonIdentity, withPeopleFolded, withPeopleUnfolded } from './boardPeople'; import type { AuditEventPage } from './services/audit'; -import type { WorkItem } from './services/workItems'; - -const item: WorkItem = { - id: 'item-1', - orgId: 'org-1', - createdBy: 'factory-rule-dispatcher', - githubProjectId: 'factory-1', - source: 'github-pr', - sourceKey: 'github-pr:12', - parentWorkItemId: null, - title: 'Ship relevance filters', - url: 'https://github.com/acme/app/pull/12', - stages: ['pr-review'], - stageHistory: [], - sessions: { - review: { - sessionId: 'session-1', - threadId: 'thread-1', - branch: 'review/relevance', - startedBy: 'user-grace', - }, - }, - metadata: { - author: 'octocat', - assignees: ['hubot'], - requestedReviewers: ['monalisa'], - }, - triageType: null, - acceptedAt: null, - description: null, - revision: 1, - createdAt: '2026-08-01T09:00:00.000Z', - updatedAt: '2026-08-05T09:00:00.000Z', -}; const activityPage: AuditEventPage = { - events: [ - { - id: 'event-1', - actorId: 'user-ada', - actorType: 'human', - action: 'factory.work_item.stage_moved', - targets: [{ type: 'work_item', id: item.id }], - metadata: {}, - occurredAt: '2026-08-05T09:00:00.000Z', - }, - ], + events: [], actors: { 'user-ada': { id: 'user-ada', name: 'Ada Lovelace', avatarUrl: 'https://avatars.example/ada.png' }, 'user-grace': { id: 'user-grace', name: 'Grace Hopper' }, + 'factory-rule-dispatcher': { id: 'factory-rule-dispatcher', name: 'Factory' }, }, }; +/** The people the server lists for a project whose cards name these three on GitHub. */ +const people = [ + { id: 'github:octocat', name: 'octocat', source: 'github' }, + { id: 'github:hubot', name: 'hubot', source: 'github' }, + { id: 'github:monalisa', name: 'monalisa', source: 'github' }, +] as const; + const asIs = boardPersonIdentity(undefined, undefined); function picks(entries: Array<[string, string]>, reviewsPullRequests = true) { @@ -78,102 +28,8 @@ function picks(entries: Array<[string, string]>, reviewsPullRequests = true) { } describe('board person filters', () => { - it('matches each role filter only through its own role, and Involves through any', () => { - const matches = (entries: Array<[string, string]>) => - workItemMatchesPeople(item, activityPage, picks(entries), asIs); - - expect(matches([['author', 'github:octocat']])).toBe(true); - expect(matches([['assignee', 'github:octocat']])).toBe(false); - expect(matches([['assignee', 'github:hubot']])).toBe(true); - expect(matches([['reviewer', 'github:monalisa']])).toBe(true); - expect(matches([['reviewer', 'github:hubot']])).toBe(false); - expect(matches([['worked', 'factory:user-ada']])).toBe(true); - expect(matches([['worked', 'factory:user-grace']])).toBe(true); - expect(matches([['author', 'factory:user-ada']])).toBe(false); - for (const participantId of ['github:octocat', 'github:hubot', 'github:monalisa', 'factory:user-ada']) { - expect(matches([['teammate', participantId]])).toBe(true); - } - expect(matches([['teammate', 'github:nobody']])).toBe(false); - expect(matches([])).toBe(true); - }); - - it('requires every role filter to match, and any person within one', () => { - const matches = (entries: Array<[string, string]>) => - workItemMatchesPeople(item, activityPage, picks(entries), asIs); - - expect( - matches([ - ['author', 'github:octocat'], - ['assignee', 'github:hubot'], - ]), - ).toBe(true); - expect( - matches([ - ['author', 'github:octocat'], - ['assignee', 'github:monalisa'], - ]), - ).toBe(false); - expect( - matches([ - ['author', 'github:octocat'], - ['reviewer', 'github:monalisa'], - ]), - ).toBe(true); - expect( - matches([ - ['author', 'github:someone-else'], - ['author', 'github:octocat'], - ]), - ).toBe(true); - }); - - it('attributes GitLab MR authors, assignees, and requested reviewers to GitLab identities', () => { - const gitlabItem: WorkItem = { ...item, source: 'gitlab-pr' }; - const matches = (entries: Array<[string, string]>) => - workItemMatchesPeople(gitlabItem, undefined, picks(entries), asIs); - - expect(matches([['author', 'gitlab:octocat']])).toBe(true); - expect(matches([['author', 'github:octocat']])).toBe(false); - expect(matches([['assignee', 'gitlab:hubot']])).toBe(true); - expect(matches([['reviewer', 'gitlab:monalisa']])).toBe(true); - }); - - it('matches what the live candidate says now alongside what the item stored', () => { - const reassigned = pullRequestCandidate({ - number: 12, - title: 'Ship relevance filters', - url: 'https://github.com/acme/app/pull/12', - author: 'octocat', - assignees: ['grace'], - requestedReviewers: [], - baseBranch: 'main', - headBranch: 'feat/relevance', - createdAt: '2026-08-01T09:00:00.000Z', - updatedAt: '2026-08-02T09:00:00.000Z', - }); - const filters = picks([ - ['author', 'github:octocat'], - ['assignee', 'github:grace'], - ]); - - expect(workItemMatchesPeople(item, activityPage, filters, asIs)).toBe(false); - expect(workItemMatchesPeople(item, activityPage, filters, asIs, reassigned)).toBe(true); - }); - - it("treats the signed-in user's GitHub login as them", () => { - const personId = boardPersonIdentity('user-octo', 'OctoCat'); - const authoredByYou = picks([['author', 'factory:user-octo']]); - - expect(workItemMatchesPeople(item, activityPage, authoredByYou, personId)).toBe(true); - expect(workItemMatchesPeople(item, activityPage, authoredByYou, asIs)).toBe(false); - expect(workItemMatchesPeople(item, activityPage, authoredByYou, boardPersonIdentity('user-octo', null))).toBe( - false, - ); - expect(workItemMatchesPeople(item, activityPage, picks([['author', 'factory:user-hubot']]), personId)).toBe(false); - }); - - it("shows the signed-in user's GitHub-login pick as them and stores it so a teammate's link still matches", () => { - const octo = boardPersonIdentity('user-octo', 'octocat'); + it("shows the signed-in user's GitHub-login pick as them and stores every id they go by", () => { + const octo = boardPersonIdentity('user-octo', 'OctoCat'); const shown = withPeopleFolded( picks([ ['teammate', 'github:octocat'], @@ -189,8 +45,19 @@ describe('board person filters', () => { const stored = withPeopleUnfolded(picks([['author', 'factory:user-octo']]), octo); expect([...stored.author]).toEqual(['factory:user-octo', 'github:octocat']); + // A teammate who opens the link folds nothing: the stored ids are the ones the server is asked. const hubot = boardPersonIdentity('user-hubot', 'hubot'); - expect(workItemMatchesPeople(item, activityPage, withPeopleFolded(stored, hubot), hubot)).toBe(true); + expect([...withPeopleUnfolded(withPeopleFolded(stored, hubot), hubot).author]).toEqual([ + 'factory:user-octo', + 'github:octocat', + ]); + }); + + it('leaves every pick as it is for someone whose GitHub login is unknown', () => { + const unlinked = boardPersonIdentity('user-octo', null); + const stored = withPeopleUnfolded(picks([['author', 'factory:user-octo']]), unlinked); + + expect([...stored.author]).toEqual(['factory:user-octo']); }); it('offers Review requested only on boards holding pull requests and ignores the retired relevance parameter', () => { @@ -199,130 +66,27 @@ describe('board person filters', () => { ['relevance', 'assigned'], ['teammate', 'github:octocat'], ]; - const custom = picks(params, false); - expect(custom.reviewer.size).toBe(0); - expect(workItemMatchesPeople(item, activityPage, custom, asIs)).toBe(true); - // A board that reviews pull requests filters by requested reviewer. + expect(picks(params, false).reviewer.size).toBe(0); expect(picks(params, true).reviewer).toEqual(new Set(['github:monalisa'])); }); - it('filters intake candidates by GitHub, GitLab, Linear, Jira, and incident.io provider metadata', () => { - const githubIssue = issueCandidate({ + it('names the signed-in user, the humans who acted, and the people cards and unfiled issues name', () => { + const unfiled = issueCandidate({ number: 7, title: 'Fix login bug', url: 'https://github.com/acme/app/issues/7', - author: 'octocat', + author: 'torvalds', assignee: 'hubot', - assignees: ['hubot', 'monalisa'], labels: [], comments: 0, createdAt: '2026-08-01T09:00:00.000Z', updatedAt: '2026-08-01T09:00:00.000Z', }); - const githubPr = pullRequestCandidate({ - number: 12, - title: 'Ship relevance filters', - url: 'https://github.com/acme/app/pull/12', - author: 'octocat', - assignees: ['hubot'], - requestedReviewers: ['monalisa'], - baseBranch: 'main', - headBranch: 'feat/relevance', - createdAt: '2026-08-01T09:00:00.000Z', - updatedAt: '2026-08-01T09:00:00.000Z', - }); - const gitlab = gitlabCandidate({ - id: '7', - externalId: 'gitlab-issue:7', - identifier: 'group/project#7', - title: 'Match provider metadata', - url: 'https://gitlab.com/group/project/-/issues/7', - state: 'opened', - stateType: 'unstarted', - priority: null, - assignee: 'Grace Hopper', - assignees: ['Grace Hopper', 'Katherine Johnson'], - author: 'Ada Lovelace', - source: 'group/project', - sourceId: 'gitlab-project:7', - labels: [], - createdAt: '2026-08-01T09:00:00.000Z', - updatedAt: '2026-08-01T09:00:00.000Z', - }); - const linear = linearCandidate({ - id: 'linear-1', - identifier: 'ENG-12', - title: 'Filter the board', - url: 'https://linear.app/acme/issue/ENG-12', - state: 'Todo', - stateType: 'unstarted', - priorityLabel: 'High', - assignee: 'Grace Hopper', - creator: 'Ada Lovelace', - team: 'Engineering', - labels: [], - createdAt: '2026-08-01T09:00:00.000Z', - updatedAt: '2026-08-01T09:00:00.000Z', - }); - const jira = jiraCandidate({ - id: 'jira-1', - identifier: 'ENG-13', - title: 'Filter the board from Jira', - url: 'https://acme.atlassian.net/browse/ENG-13', - state: 'To Do', - stateType: 'unstarted', - priorityLabel: 'High', - assignee: 'Grace Hopper', - author: 'Ada Lovelace', - project: 'ENG', - site: 'acme.atlassian.net', - labels: [], - createdAt: '2026-08-01T09:00:00.000Z', - updatedAt: '2026-08-01T09:00:00.000Z', - sourceId: '10001', - }); - - const incidentio = incidentioCandidate({ - id: 'incidentio:follow-up:01HFOLLOWUP', - identifier: 'INC-42', - title: 'Add database failover alert', - url: 'https://app.incident.io/org/follow-ups/01HFOLLOWUP', - state: 'outstanding', - stateType: 'unstarted', - priorityLabel: 'Urgent', - assignee: 'Grace Hopper', - author: 'Ada Lovelace', - incident: 'incident-1', - labels: [], - createdAt: '2026-08-01T09:00:00.000Z', - updatedAt: '2026-08-01T09:00:00.000Z', - sourceId: 'incidentio:follow-ups', - }); - - const matches = (candidate: Parameters[0], fieldId: string, participantId: string) => - candidateMatchesPeople(candidate, picks([[fieldId, participantId]]), asIs); - - expect(matches(githubIssue, 'assignee', 'github:hubot')).toBe(true); - expect(matches(githubIssue, 'assignee', 'github:monalisa')).toBe(true); - expect(matches(githubIssue, 'author', 'github:hubot')).toBe(false); - expect(matches(githubPr, 'reviewer', 'github:monalisa')).toBe(true); - expect(matches(gitlab, 'author', 'gitlab:ada lovelace')).toBe(true); - expect(matches(gitlab, 'assignee', 'gitlab:katherine johnson')).toBe(true); - expect(matches(linear, 'author', 'linear:ada lovelace')).toBe(true); - expect(matches(linear, 'assignee', 'linear:grace hopper')).toBe(true); - expect(matches(jira, 'author', 'jira:ada lovelace')).toBe(true); - expect(matches(jira, 'assignee', 'jira:grace hopper')).toBe(true); - expect(matches(incidentio, 'author', 'incidentio:ada lovelace')).toBe(true); - expect(matches(incidentio, 'assignee', 'incidentio:grace hopper')).toBe(true); - expect(matches(linear, 'worked', 'linear:ada lovelace')).toBe(false); - }); - - it('builds a named people list from auth, audit, and provider metadata without raw Factory ids', () => { const participants = boardParticipants({ - items: [item], - candidates: [], + people, + candidates: [unfiled], activityPage, currentUser: { userId: 'user-current', name: 'Katherine Johnson' }, personId: asIs, @@ -335,6 +99,7 @@ describe('board person filters', () => { 'factory:user-current', 'github:monalisa', 'github:octocat', + 'github:torvalds', ]); expect(participants.find(participant => participant.id === 'github:octocat')?.avatarUrl).toContain( 'github.com/octocat.png', @@ -344,7 +109,7 @@ describe('board person filters', () => { it('lists the signed-in user once, with their GitHub avatar, instead of beside their GitHub login', () => { const participants = boardParticipants({ - items: [item], + people, candidates: [], activityPage, currentUser: { userId: 'user-octo', name: 'Octo Cat' }, diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardPeople.ts b/mastracode/factory-ui/src/ui/domains/factory/boardPeople.ts index b7f470497cc..a9c8e29d6ab 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardPeople.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardPeople.ts @@ -1,36 +1,13 @@ import { isHumanActorId } from '@mastra/factory/storage/domains/audit/actors'; +import { BOARD_PERSON_FIELDS, factoryParticipantId, providerPeople } from '@mastra/factory/work-items/card-people'; +import type { ProviderPerson } from '@mastra/factory/work-items/card-people'; import type { BoardCandidate } from './boardCandidates'; -import { sourceMetadata } from './boardItems'; import type { BoardFilterFieldId, BoardFilterState } from './boardFilters'; import type { AuditActorProfile, AuditEventPage } from './services/audit'; -import type { WorkItem } from './services/workItems'; -import { workItemHumanActorIds } from './workItemActivity'; - -const BOARD_PERSON_ROLES = ['worked', 'authored', 'assigned', 'review-requested'] as const; -type BoardPersonRole = (typeof BOARD_PERSON_ROLES)[number]; -type BoardRelations = Record>; - -/** One filter per person role, plus `teammate` (shown as Involves) for any role. */ -export const BOARD_PERSON_FIELDS = ['teammate', 'author', 'assignee', 'reviewer', 'worked'] as const; -export type BoardPersonFieldId = (typeof BOARD_PERSON_FIELDS)[number]; - -const PERSON_FIELD_ROLES: Record = { - teammate: BOARD_PERSON_ROLES, - author: ['authored'], - assignee: ['assigned'], - reviewer: ['review-requested'], - worked: ['worked'], -}; - -export type BoardPeopleFilters = Pick; export interface BoardParticipant extends AuditActorProfile { - source: 'factory' | 'github' | 'gitlab' | 'linear' | 'jira' | 'incidentio'; -} - -export function factoryParticipantId(userId: string): string { - return `factory:${userId}`; + source: 'factory' | ProviderPerson['source']; } /** `fold` names every identity of one person by one participant id; `aliases` lists every id that one stands for. */ @@ -64,187 +41,39 @@ export function withPeopleFolded(filters: BoardFilterState, personId: PersonIden return withPeopleMapped(filters, picked => [personId.fold(picked)]); } -/** What links and saved views store: every id a pick stands for, so they still match for someone who can't fold it. */ +/** + * What links, saved views and the server's listing read: every id a pick stands for, so they + * still match for someone who can't fold it. + */ export function withPeopleUnfolded(filters: BoardFilterState, personId: PersonIdentity): BoardFilterState { return withPeopleMapped(filters, personId.aliases); } -interface RelatedCard { - workItem?: WorkItem['workItem']; - source: WorkItem['source']; - metadata: Record; -} - -function metadataString(metadata: Record, key: string): string | undefined { - const value = metadata[key]; - return typeof value === 'string' && value.trim() ? value.trim() : undefined; -} - -function metadataStrings(metadata: Record, key: string): string[] { - const value = metadata[key]; - if (!Array.isArray(value)) return []; - return value.flatMap(entry => (typeof entry === 'string' && entry.trim() ? [entry.trim()] : [])); -} - -function externalId(source: RelatedCard['source'], name: string): string | undefined { - if (source === 'github-issue' || source === 'github-pr') return `github:${name.toLowerCase()}`; - if (source === 'gitlab-issue' || source === 'gitlab-pr') return `gitlab:${name.toLowerCase()}`; - if (source === 'linear-issue') return `linear:${name.toLowerCase()}`; - if (source === 'jira-issue') return `jira:${name.toLowerCase()}`; - if (source === 'incidentio-follow-up') return `incidentio:${name.toLowerCase()}`; - return undefined; -} - -function externalProfile(source: RelatedCard['source'], name: string): BoardParticipant | undefined { - const id = externalId(source, name); - if (!id) return undefined; - if (source === 'github-issue' || source === 'github-pr') { - return { - id, - name, - avatarUrl: `https://github.com/${encodeURIComponent(name)}.png?size=64`, - source: 'github', - }; - } - if (source === 'gitlab-issue' || source === 'gitlab-pr') return { id, name, source: 'gitlab' }; - if (source === 'jira-issue') return { id, name, source: 'jira' }; - if (source === 'incidentio-follow-up') return { id, name, source: 'incidentio' }; - return { id, name, source: 'linear' }; -} - -function externalCreator(card: RelatedCard): string | undefined { - if ( - card.source === 'github-issue' || - card.source === 'github-pr' || - card.source === 'gitlab-issue' || - card.source === 'gitlab-pr' - ) { - return metadataString(sourceMetadata(card), 'author'); - } - if (card.source === 'linear-issue' || card.source === 'jira-issue' || card.source === 'incidentio-follow-up') { - return ( - metadataString(sourceMetadata(card), 'creator') ?? - metadataString(sourceMetadata(card), 'linearCreator') ?? - metadataString(sourceMetadata(card), 'author') - ); - } - return undefined; -} - -function externalAssignees(card: RelatedCard): string[] { - if ( - card.source === 'github-issue' || - card.source === 'github-pr' || - card.source === 'gitlab-issue' || - card.source === 'gitlab-pr' - ) { - const assignees = metadataStrings(sourceMetadata(card), 'assignees'); - const assignee = metadataString(sourceMetadata(card), 'assignee'); - return [...new Set([...assignees, ...(assignee ? [assignee] : [])])]; - } - if (card.source === 'linear-issue' || card.source === 'jira-issue' || card.source === 'incidentio-follow-up') { - const assignee = - metadataString(sourceMetadata(card), 'assignee') ?? metadataString(sourceMetadata(card), 'linearAssignee'); - return assignee ? [assignee] : []; - } - return []; -} - -function requestedReviewers(card: RelatedCard): string[] { - if (card.source !== 'github-pr' && card.source !== 'gitlab-pr') return []; - return metadataStrings(sourceMetadata(card), 'requestedReviewers'); -} - -function externalIds(source: RelatedCard['source'], names: readonly string[]): Set { - return new Set( - names.flatMap(name => { - const id = externalId(source, name); - return id ? [id] : []; - }), - ); -} - -function cardRelations(card: RelatedCard): BoardRelations { - const creator = externalCreator(card); - return { - worked: new Set(), - authored: externalIds(card.source, creator ? [creator] : []), - assigned: externalIds(card.source, externalAssignees(card)), - 'review-requested': externalIds(card.source, requestedReviewers(card)), - }; -} - -function targetsWorkItem(event: NonNullable['events'][number], workItemId: string): boolean { - return event.targets.some(target => target.type === 'work_item' && target.id === workItemId); -} - -/** The item's own relations, plus whatever its live intake candidate now says (a reassignment, a new reviewer). */ -function workItemRelations( - item: WorkItem, - activityPage: AuditEventPage | undefined, - liveCandidate: BoardCandidate | undefined, -): BoardRelations { - const relations = cardRelations(item); - for (const actorId of workItemHumanActorIds(item)) relations.worked.add(factoryParticipantId(actorId)); - for (const event of activityPage?.events ?? []) { - if (event.actorType === 'human' && isHumanActorId(event.actorId) && targetsWorkItem(event, item.id)) { - relations.worked.add(factoryParticipantId(event.actorId)); - } - } - if (item.source === 'manual' && isHumanActorId(item.createdBy)) { - relations.authored.add(factoryParticipantId(item.createdBy)); - } - if (liveCandidate) { - const live = cardRelations(liveCandidate); - for (const role of BOARD_PERSON_ROLES) for (const id of live[role]) relations[role].add(id); - } - return relations; -} - -/** Each person filter must match (AND); within one, any picked person in any of its roles will do (OR). */ -function matchesPeople(relations: BoardRelations, people: BoardPeopleFilters, personId: PersonIdentity): boolean { - return BOARD_PERSON_FIELDS.every(fieldId => { - const picked = people[fieldId]; - if (picked.size === 0) return true; - return PERSON_FIELD_ROLES[fieldId].some(role => [...relations[role]].some(id => picked.has(personId.fold(id)))); - }); -} - -export function workItemMatchesPeople( - item: WorkItem, - activityPage: AuditEventPage | undefined, - people: BoardPeopleFilters, - personId: PersonIdentity, - liveCandidate?: BoardCandidate, -): boolean { - if (BOARD_PERSON_FIELDS.every(fieldId => people[fieldId].size === 0)) return true; - return matchesPeople(workItemRelations(item, activityPage, liveCandidate), people, personId); -} - -export function candidateMatchesPeople( - candidate: BoardCandidate, - people: BoardPeopleFilters, - personId: PersonIdentity, -): boolean { - return matchesPeople(cardRelations(candidate), people, personId); +function providerParticipant(person: ProviderPerson): BoardParticipant { + if (person.source !== 'github') return person; + return { ...person, avatarUrl: `https://github.com/${encodeURIComponent(person.name)}.png?size=64` }; } +/** + * The people a person filter offers: the signed-in user, everyone who acted on the project's + * cards, and everyone a card or an issue not filed yet names. + */ export function boardParticipants({ - items, + people, candidates, activityPage, currentUser, personId, }: { - items: readonly WorkItem[]; + /** The people the project's cards name, as the server lists them. */ + people: readonly ProviderPerson[]; candidates: readonly BoardCandidate[]; activityPage: AuditEventPage | undefined; currentUser?: { userId?: string; name?: string; email?: string }; personId: PersonIdentity; }): BoardParticipant[] { const participants = new Map(); - const add = (participant: BoardParticipant | undefined) => { - if (!participant) return; + const add = (participant: BoardParticipant) => { const id = personId.fold(participant.id); const existing = participants.get(id); if (!existing) { @@ -271,19 +100,12 @@ export function boardParticipants({ add({ ...profile, id: factoryParticipantId(actorId), source: 'factory' }); } - for (const item of items) { - for (const actorId of workItemHumanActorIds(item)) { - const profile = activityPage?.actors[actorId]; - if (profile) add({ ...profile, id: factoryParticipantId(actorId), source: 'factory' }); + for (const person of people) add(providerParticipant(person)); + for (const candidate of candidates) { + for (const named of Object.values(providerPeople(candidate))) { + for (const person of named) add(providerParticipant(person)); } } - for (const card of [...items, ...candidates]) { - const creator = externalCreator(card); - add(creator ? externalProfile(card.source, creator) : undefined); - for (const assignee of externalAssignees(card)) add(externalProfile(card.source, assignee)); - for (const reviewer of requestedReviewers(card)) add(externalProfile(card.source, reviewer)); - } - return [...participants.values()].sort((left, right) => left.name.localeCompare(right.name)); } diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardPhases.test.ts b/mastracode/factory-ui/src/ui/domains/factory/boardPhases.test.ts new file mode 100644 index 00000000000..8392064c543 --- /dev/null +++ b/mastracode/factory-ui/src/ui/domains/factory/boardPhases.test.ts @@ -0,0 +1,218 @@ +import { describe, expect, it } from 'vitest'; + +import type { BoardPhasesSnapshot } from '../../../hooks/useWorkItems'; +import { shownBoardPhases } from './boardPhases'; +import type { ShownPhase } from './boardPhases'; +import type { WorkItem } from './services/workItems'; + +const stages = [{ id: 'intake' }, { id: 'planning' }, { id: 'done' }]; + +function card(id: string, cardStages: string[]): WorkItem { + return { + id, + orgId: 'org-1', + createdBy: 'user-1', + githubProjectId: 'fp-1', + board: 'work', + source: 'manual', + sourceKey: null, + parentWorkItemId: null, + title: id, + url: null, + stages: cardStages, + stageHistory: [], + sessions: {}, + metadata: {}, + triageType: null, + acceptedAt: null, + description: null, + revision: 1, + createdAt: '2026-08-01T09:00:00.000Z', + updatedAt: '2026-08-01T09:00:00.000Z', + }; +} + +function snapshot( + phases: BoardPhasesSnapshot['phases'], + workItems: WorkItem[], + asked?: BoardPhasesSnapshot['asked'], +): BoardPhasesSnapshot { + return { + phases, + workItems, + ...(asked ? { asked } : {}), + matchingTotal: phases.reduce((sum, listed) => sum + listed.total, 0), + boardTotal: phases.reduce((sum, listed) => sum + listed.total, 0), + runningSessionIds: [], + parkedSessionIds: [], + }; +} + +function titles(shown: ReadonlyMap, stage: string) { + return shown.get(stage)?.cards.map(item => item.id); +} + +describe('shownBoardPhases', () => { + it('shows each phase its listed cards in the order the server listed them, whatever order the bodies came in', () => { + const shown = shownBoardPhases( + snapshot( + [ + { phase: 'intake', total: 2, ids: ['b', 'a'] }, + { phase: 'planning', total: 1, ids: ['c'] }, + { phase: 'done', total: 0, ids: [] }, + ], + [card('a', ['intake']), card('c', ['planning']), card('b', [])], + ), + stages, + ); + + expect(titles(shown, 'intake')).toEqual(['b', 'a']); + expect(titles(shown, 'planning')).toEqual(['c']); + expect(shown.get('intake')).toMatchObject({ total: 2, listedAll: true }); + }); + + it('says a phase has more to load while the server lists fewer cards than match', () => { + const shown = shownBoardPhases( + snapshot([{ phase: 'intake', total: 120, ids: ['a', 'b'] }], [card('a', ['intake']), card('b', ['intake'])]), + stages, + ); + + expect(shown.get('intake')).toMatchObject({ total: 120, listedAll: false }); + expect(shown.get('planning')).toEqual({ cards: [], total: 0, listed: 0, listedAll: true }); + }); + + it('shows a card moved since the read on top of the phase it entered, gone from the one it left, and counts follow', () => { + const shown = shownBoardPhases( + snapshot( + [ + { phase: 'intake', total: 120, ids: ['a', 'b'] }, + { phase: 'planning', total: 1, ids: ['c'] }, + ], + // `a` was listed in Intake; its body now says Planning. + [card('a', ['planning']), card('b', ['intake']), card('c', ['planning'])], + ), + stages, + ); + + expect(titles(shown, 'intake')).toEqual(['b']); + expect(titles(shown, 'planning')).toEqual(['a', 'c']); + expect(shown.get('intake')?.total).toBe(119); + expect(shown.get('planning')?.total).toBe(2); + // Intake still has cards the server did not list: the move does not hide that. + expect(shown.get('intake')?.listedAll).toBe(false); + }); + + it('keeps a card in both phases it sits in, and leaves out a card held only as a relative', () => { + const shown = shownBoardPhases( + snapshot( + [ + { phase: 'intake', total: 1, ids: ['a'] }, + { phase: 'planning', total: 1, ids: ['a'] }, + ], + [card('a', ['intake', 'planning']), card('parent', ['done'])], + ), + stages, + ); + + expect(titles(shown, 'intake')).toEqual(['a']); + expect(titles(shown, 'planning')).toEqual(['a']); + expect(titles(shown, 'done')).toEqual([]); + expect(shown.get('planning')?.total).toBe(1); + }); + + it('leaves a card of two phases out of the one that holds it below its window, where nothing moved', () => { + const shown = shownBoardPhases( + snapshot( + [ + { phase: 'intake', total: 1, ids: ['both'] }, + // Planning counts `both` among its 51 cards and lists it further down than this window. + { phase: 'planning', total: 51, ids: ['c'] }, + ], + [card('both', ['intake', 'planning']), card('c', ['planning'])], + ), + stages, + ); + + expect(titles(shown, 'intake')).toEqual(['both']); + expect(titles(shown, 'planning')).toEqual(['c']); + expect(shown.get('planning')).toMatchObject({ total: 51, listed: 1, listedAll: false }); + }); + + it('shows empty phases with nothing to load before the first answer', () => { + const shown = shownBoardPhases(undefined, stages); + + expect([...shown.keys()]).toEqual(['intake', 'planning', 'done']); + expect(shown.get('done')).toEqual({ cards: [], total: 0, listed: 0, listedAll: true }); + }); + + it('shows the asked card on top of a phase that holds it deeper than it lists, without counting it twice', () => { + const shown = shownBoardPhases( + snapshot( + [ + { phase: 'intake', total: 120, ids: ['a', 'b'] }, + { phase: 'planning', total: 1, ids: ['c'] }, + ], + [card('a', ['intake']), card('b', ['intake']), card('c', ['planning']), card('deep', ['intake'])], + { id: 'deep', phases: ['intake'] }, + ), + stages, + ); + + expect(titles(shown, 'intake')).toEqual(['deep', 'a', 'b']); + expect(titles(shown, 'planning')).toEqual(['c']); + // The phase's total counted the card before it was asked for, and a deeper window counts from the two listed. + expect(shown.get('intake')).toMatchObject({ total: 120, listed: 2, listedAll: false }); + }); + + it('shows the asked card once where the phase lists it, and on top of another phase that holds it deeper', () => { + const shown = shownBoardPhases( + snapshot( + [ + { phase: 'intake', total: 2, ids: ['both', 'a'] }, + { phase: 'planning', total: 80, ids: ['c'] }, + ], + [card('both', ['intake', 'planning']), card('a', ['intake']), card('c', ['planning'])], + { id: 'both', phases: ['intake', 'planning'] }, + ), + stages, + ); + + expect(titles(shown, 'intake')).toEqual(['both', 'a']); + expect(titles(shown, 'planning')).toEqual(['both', 'c']); + expect(shown.get('intake')?.total).toBe(2); + expect(shown.get('planning')?.total).toBe(80); + }); + + it('shows nowhere an asked card the view leaves out', () => { + const shown = shownBoardPhases( + snapshot([{ phase: 'intake', total: 1, ids: ['a'] }], [card('a', ['intake']), card('hidden', ['intake'])], { + id: 'hidden', + phases: [], + }), + stages, + ); + + expect(titles(shown, 'intake')).toEqual(['a']); + expect(shown.get('intake')?.total).toBe(1); + }); + + it('shows an asked card moved since the read on top of the phase it entered, not the one that held it', () => { + const shown = shownBoardPhases( + snapshot( + [ + { phase: 'intake', total: 120, ids: ['a'] }, + { phase: 'planning', total: 1, ids: ['c'] }, + ], + // The view held `deep` far down Intake; its body now says Planning. + [card('a', ['intake']), card('c', ['planning']), card('deep', ['planning'])], + { id: 'deep', phases: ['intake'] }, + ), + stages, + ); + + expect(titles(shown, 'intake')).toEqual(['a']); + expect(titles(shown, 'planning')).toEqual(['deep', 'c']); + expect(shown.get('intake')?.total).toBe(119); + expect(shown.get('planning')?.total).toBe(2); + }); +}); diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardPhases.ts b/mastracode/factory-ui/src/ui/domains/factory/boardPhases.ts new file mode 100644 index 00000000000..fb676410498 --- /dev/null +++ b/mastracode/factory-ui/src/ui/domains/factory/boardPhases.ts @@ -0,0 +1,72 @@ +import type { BoardPhasesSnapshot } from '../../../hooks/useWorkItems'; +import { itemAppearsInStage } from './boardStages'; +import type { WorkItem } from './services/workItems'; +import type { BoardStageId } from './stages'; + +/** What a board column shows of one phase, from one read of its view. */ +export interface ShownPhase { + /** The cards shown, in the view's order. */ + cards: WorkItem[]; + /** How many cards of the phase match the view, listed or not. */ + total: number; + /** How many cards the server listed: what a deeper window is counted from. */ + listed: number; + /** Whether the server listed every matching card, so nothing is left to load. */ + listedAll: boolean; +} + +const NO_CARDS: WorkItem[] = []; + +/** + * The cards each phase shows. The server decided which cards the view lists and in what order. + * Where a named card sits is read from the card itself, so a card moved in this tab leaves its + * phase and tops the one it entered at once, before the next read lists it there. The asked card + * tops each phase that holds it deeper than it is listed: it shows without the cards above it. + * A card of two phases that one of them holds below its window has not moved: it stays out of it. + */ +export function shownBoardPhases( + snapshot: BoardPhasesSnapshot | undefined, + stages: ReadonlyArray<{ id: BoardStageId }>, +): ReadonlyMap { + const shown = new Map(); + if (!snapshot) { + for (const stage of stages) shown.set(stage.id, { cards: NO_CARDS, total: 0, listed: 0, listedAll: true }); + return shown; + } + const held = new Map(snapshot.workItems.map(card => [card.id, card])); + const asked = snapshot.asked; + // The phases the read put each card in: the ones that list it, and the ones that hold the asked + // card. An asked card the view leaves out is in no phase. + const put = new Map(); + for (const listed of snapshot.phases) { + for (const id of listed.ids) put.set(id, [...(put.get(id) ?? []), listed.phase]); + } + if (asked && asked.phases.length > 0) put.set(asked.id, [...(put.get(asked.id) ?? []), ...asked.phases]); + // A card moved in this tab has left a phase the read put it in. + const moved = [...put].flatMap(([id, phases]) => { + const card = held.get(id); + return card && phases.some(phase => !itemAppearsInStage(card, phase, stages)) ? [id] : []; + }); + for (const stage of stages) { + const listed = snapshot.phases.find(candidate => candidate.phase === stage.id); + const ids = new Set(listed?.ids); + const sits = (id: string) => { + const card = held.get(id); + return card && itemAppearsInStage(card, stage.id, stages) ? [card] : []; + }; + const stayed = [...ids].flatMap(sits); + // Held by the phase below what it lists: its total counts the card already. + const heldDeeper = asked !== undefined && asked.phases.includes(stage.id) && !ids.has(asked.id); + const deeper = heldDeeper ? sits(asked.id) : []; + const arrived = moved.filter(id => !ids.has(id) && !(heldDeeper && id === asked.id)).flatMap(sits); + // The cards the total counted that have left the phase since: the listed ones, and the asked one. + const left = ids.size - stayed.length + (heldDeeper ? 1 - deeper.length : 0); + shown.set(stage.id, { + cards: [...arrived, ...deeper, ...stayed], + total: (listed?.total ?? 0) - left + arrived.length, + listed: ids.size, + listedAll: ids.size >= (listed?.total ?? 0), + }); + } + return shown; +} diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardPhasesRequest.test.ts b/mastracode/factory-ui/src/ui/domains/factory/boardPhasesRequest.test.ts new file mode 100644 index 00000000000..5873d9ab39a --- /dev/null +++ b/mastracode/factory-ui/src/ui/domains/factory/boardPhasesRequest.test.ts @@ -0,0 +1,61 @@ +import { describe, expect, it } from 'vitest'; + +import { boardPhasesRequest, deeperPhaseWindow } from './boardPhasesRequest'; +import { boardFiltersFromParams } from './boardFilters'; + +const NO_FILTERS = boardFiltersFromParams(new URLSearchParams(), true); +const CARD_ID = '3f2c1a9e-5b7d-4c1e-9a2f-0d6e8b4c7a15'; + +function request(overrides: Partial[0]> = {}) { + return boardPhasesRequest({ + board: 'work', + sort: 'recent', + search: '', + filters: NO_FILTERS, + windows: {}, + item: undefined, + ...overrides, + }); +} + +describe('boardPhasesRequest', () => { + it('asks the same thing whatever order the filters were picked in, so one view is one cached read', () => { + const first = request({ + filters: boardFiltersFromParams(new URLSearchParams('label=p1&label=bug&author=github%3Aada'), true), + }); + const second = request({ + filters: boardFiltersFromParams(new URLSearchParams('author=github%3Aada&label=bug&label=p1'), true), + }); + + expect(first.filters).toEqual({ label: ['bug', 'p1'], author: ['github:ada'] }); + expect(JSON.stringify(first)).toBe(JSON.stringify(second)); + }); + + it('names no filter the view leaves empty', () => { + expect(request().filters).toEqual({}); + }); + + it('asks for the search without its outer spaces and no longer than the server accepts', () => { + expect(request({ search: ' login bug ' }).q).toBe('login bug'); + expect(request({ search: 'x'.repeat(260) }).q).toHaveLength(200); + }); + + it('names the linked card only when the link holds a card id, which is all the server accepts', () => { + expect(request({ item: CARD_ID }).item).toBe(CARD_ID); + expect(request({ item: 'not-a-card' })).not.toHaveProperty('item'); + expect(request()).not.toHaveProperty('item'); + }); +}); + +describe('deeperPhaseWindow', () => { + it('doubles what a column lists, starting from the first page', () => { + expect(deeperPhaseWindow(50)).toBe(100); + expect(deeperPhaseWindow(100)).toBe(200); + // A column that lost cards since its read still deepens past its first page. + expect(deeperPhaseWindow(48)).toBe(100); + }); + + it('never asks deeper than the server accepts', () => { + expect(deeperPhaseWindow(900_000)).toBe(999_999); + }); +}); diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardPhasesRequest.ts b/mastracode/factory-ui/src/ui/domains/factory/boardPhasesRequest.ts new file mode 100644 index 00000000000..1b5ce707794 --- /dev/null +++ b/mastracode/factory-ui/src/ui/domains/factory/boardPhasesRequest.ts @@ -0,0 +1,58 @@ +import type { BoardPhasesRequest } from '../../../api/types'; +import { BOARD_FILTER_FIELDS } from './boardFilters'; +import type { BoardFilterState } from './boardFilters'; +import type { BoardSort } from './boardSort'; + +/** How many cards the server lists in a phase the request names no window for. */ +const PHASE_PAGE = 50; +/** The deepest window the server accepts. */ +const DEEPEST_PHASE_WINDOW = 999_999; +/** The longest search the server accepts. */ +const LONGEST_SEARCH = 200; +const CARD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; + +/** Whether `text` is a card id. The server refuses a card named by anything else, and nothing else names one. */ +export function isCardId(text: string): boolean { + return CARD_ID.test(text); +} + +/** + * What the server is asked to list a board view. The page and the route loader both build it here, + * so the loader's read is the one the page then waits for. + */ +export function boardPhasesRequest({ + board, + sort, + search, + filters, + windows, + item, +}: { + board: string; + sort: BoardSort; + search: string; + /** As links and saved views store them: every id a picked person stands for. */ + filters: BoardFilterState; + /** How many cards each deepened phase lists. */ + windows: Readonly>; + /** The card a link names, to show however deep its phase holds it. */ + item: string | undefined; +}): BoardPhasesRequest { + const picked: BoardPhasesRequest['filters'] = {}; + for (const filter of BOARD_FILTER_FIELDS) { + if (filters[filter].size > 0) picked[filter] = [...filters[filter]].sort(); + } + return { + board, + sort, + q: search.trim().slice(0, LONGEST_SEARCH), + filters: picked, + windows, + ...(item !== undefined && isCardId(item) ? { item } : {}), + }; +} + +/** The window that lists a phase twice as deep as the `listed` cards it shows. */ +export function deeperPhaseWindow(listed: number): number { + return Math.min(Math.max(listed, PHASE_PAGE) * 2, DEEPEST_PHASE_WINDOW); +} diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardSavedViews.ts b/mastracode/factory-ui/src/ui/domains/factory/boardSavedViews.ts index 34624430827..3f8917dee0d 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardSavedViews.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardSavedViews.ts @@ -1,8 +1,7 @@ import { z } from 'zod'; import { BOARD_LAYOUTS, DEFAULT_BOARD_LAYOUT } from './boardLayout'; -import { BOARD_SORTS } from './boardOrder'; -import { DEFAULT_BOARD_SORT } from './boardSort'; +import { BOARD_SORTS, DEFAULT_BOARD_SORT } from './boardSort'; /** Query parameter holding the selected saved view, so a refresh or a reopen from the sidebar keeps it. */ export const BOARD_VIEW_QUERY = 'view'; diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardSort.ts b/mastracode/factory-ui/src/ui/domains/factory/boardSort.ts index f05ac393a80..2645a916d40 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardSort.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardSort.ts @@ -1,5 +1,13 @@ -import { BOARD_SORTS } from './boardOrder'; -import type { BoardSort } from './boardOrder'; +import type { BoardPhasesSort } from '../../../api/types'; + +/** The orders the server lists a phase in. */ +export type BoardSort = BoardPhasesSort; +export const BOARD_SORTS = [ + 'recent', + 'recent-mine', + 'created-newest', + 'created-oldest', +] as const satisfies readonly BoardSort[]; export const BOARD_SORT_QUERY = 'sort'; diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardSourceFilters.test.ts b/mastracode/factory-ui/src/ui/domains/factory/boardSourceFilters.test.ts index b29aea62245..3246eade141 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardSourceFilters.test.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardSourceFilters.test.ts @@ -1,5 +1,4 @@ import { describe, expect, it } from 'vitest'; -import { linearCandidate } from './boardCandidates'; import { boardFilterItems, boardFilterParams, @@ -7,9 +6,6 @@ import { boardFiltersFromParams, withBoardFilterValues, } from './boardFilters'; -import { boardSource, cardMatchesSourceFilters } from './boardSourceFilters'; -import type { WorkItem } from './services/workItems'; -import { linearIssue, sourceCards } from '../../__tests__/fixtures/boardSourceFilters'; describe('Board source filters', () => { it('preserves every filter through URL and saved view filters', () => { @@ -27,37 +23,9 @@ describe('Board source filters', () => { expect(url.get('sort')).toBe('created-newest'); }); - it('does not use an old stored project when the live issue has no project', () => { - const card = sourceCards[0]; - const filters = boardFiltersFromParams(new URLSearchParams('linearProject=project-a'), true); - expect(cardMatchesSourceFilters(card, filters)).toBe(true); - expect(cardMatchesSourceFilters(card, filters, linearCandidate(linearIssue('ENG-102', null)))).toBe(false); - }); - - it('narrows only Linear cards by project when other sources are picked too', () => { - const github: Pick = { source: 'github-issue', metadata: {} }; - const filters = boardFiltersFromParams( - new URLSearchParams('source=github&source=linear&linearProject=project-b'), - true, - ); - expect(cardMatchesSourceFilters(github, filters)).toBe(true); - expect(cardMatchesSourceFilters(sourceCards[0], filters)).toBe(false); - expect( - cardMatchesSourceFilters(github, boardFiltersFromParams(new URLSearchParams('linearProject=project-b'), true)), - ).toBe(false); - }); - it('drops picked Linear projects once Linear is no longer a picked source', () => { const filters = boardFiltersFromParams(new URLSearchParams('source=linear&linearProject=project-a'), true); expect([...withBoardFilterValues(filters, 'source', ['linear', 'github']).linearProject]).toEqual(['project-a']); expect(withBoardFilterValues(filters, 'source', ['github']).linearProject.size).toBe(0); }); - - it('groups issue and pull request sources under their providers', () => { - expect(boardSource('github-issue')).toBe('github'); - expect(boardSource('github-pr')).toBe('github'); - expect(boardSource('gitlab-pr')).toBe('gitlab'); - expect(boardSource('incidentio-follow-up')).toBe('incidentio'); - expect(boardSource('manual')).toBe('manual'); - }); }); diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardSourceFilters.ts b/mastracode/factory-ui/src/ui/domains/factory/boardSourceFilters.ts index c3600afa9ee..f4bfc7553ac 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardSourceFilters.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardSourceFilters.ts @@ -1,11 +1,5 @@ -import type { BoardCandidate } from './boardCandidates'; -import { sourceMetadata } from './boardItems'; -import type { BoardFilterState } from './boardFilters'; -import { cardHasPullRequest } from './services/workItems'; -import type { WorkItem, WorkItemSource } from './services/workItems'; - -/** The source filter value for cards carrying a pull or merge request; where `/review` now leads. */ -export const PULL_REQUEST_SOURCE_FILTER = 'pull-request'; +import { pickedBoardSources, PULL_REQUEST_SOURCE_FILTER } from '@mastra/factory/work-items/card-source-filters'; +import type { SourceFilters } from '@mastra/factory/work-items/card-source-filters'; export const BOARD_SOURCE_OPTIONS = [ { value: 'github', label: 'GitHub' }, @@ -18,38 +12,7 @@ export const BOARD_SOURCE_OPTIONS = [ { value: PULL_REQUEST_SOURCE_FILTER, label: 'Pull requests' }, ] as const; -type BoardSourceFilters = Pick; - -export function boardSource(source: WorkItemSource): string { - if (source === 'incidentio-follow-up') return 'incidentio'; - return source.split('-')[0]; -} - -/** Sources the board shows; empty means all. A Linear project picked on its own implies Linear. */ -export function pickedBoardSources(filters: BoardSourceFilters): ReadonlySet { - if (filters.source.size === 0 && filters.linearProject.size > 0) return new Set(['linear']); - return filters.source; -} - /** Source and project filters determine which intake feeds to browse. */ -export function hasBoardSourceFilters(filters: BoardSourceFilters): boolean { +export function hasBoardSourceFilters(filters: SourceFilters): boolean { return pickedBoardSources(filters).size > 0; } - -/** Live metadata wins, including an issue moved out of a project; stored metadata covers older pages. */ -export function cardMatchesSourceFilters( - card: Pick, - filters: BoardSourceFilters, - liveCandidate?: BoardCandidate, -): boolean { - const sources = pickedBoardSources(filters); - if ( - sources.size > 0 && - !sources.has(boardSource(card.source)) && - !(sources.has(PULL_REQUEST_SOURCE_FILTER) && cardHasPullRequest(card)) - ) - return false; - if (card.source !== 'linear-issue' || filters.linearProject.size === 0) return true; - const projectId = sourceMetadata(liveCandidate ?? card).linearProjectId; - return typeof projectId === 'string' && filters.linearProject.has(projectId); -} diff --git a/mastracode/factory-ui/src/ui/domains/factory/boardStages.ts b/mastracode/factory-ui/src/ui/domains/factory/boardStages.ts index da9562848fa..9c0a46e3114 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/boardStages.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/boardStages.ts @@ -7,10 +7,6 @@ import type { BoardStage, BoardStageId } from './stages'; export type BoardKind = string; -export function belongsToBoard(item: WorkItem, kind: BoardKind): boolean { - return itemBoard(item) === kind; -} - /** Whether `item` shows in the `stage` column; a card in no known column shows in the first one, where cards start. */ export function itemAppearsInStage( item: WorkItem, diff --git a/mastracode/factory-ui/src/ui/domains/factory/cardPrimaryAction.ts b/mastracode/factory-ui/src/ui/domains/factory/cardPrimaryAction.ts index b0387f3fe02..3adca398287 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/cardPrimaryAction.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/cardPrimaryAction.ts @@ -1,9 +1,10 @@ import { needsApproval } from '@mastra/factory/rules/types'; +import { metadataLabels } from '@mastra/factory/work-items/card-labels'; import type { BoardCardState, BoardCardStatus } from './boardCardState'; import { allowsMove, boardLoop, phaseKindOf } from './boardFlow'; import type { BoardInfo, BoardLoop } from './boardFlow'; -import { itemSessionSpec, metadataLabels, pullRequestStatusForItem, pullRequestStatusForSource } from './boardItems'; +import { itemSessionSpec, pullRequestStatusForItem, pullRequestStatusForSource } from './boardItems'; import { attachedPullRequestSource, cardHasPullRequest, isPullRequestSource } from './services/workItems'; import type { WorkItem, WorkItemSessionRef } from './services/workItems'; import type { BoardStageId } from './stages'; diff --git a/mastracode/factory-ui/src/ui/domains/factory/components/BoardCardParts.tsx b/mastracode/factory-ui/src/ui/domains/factory/components/BoardCardParts.tsx index ab991824c42..7b60330464c 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/components/BoardCardParts.tsx +++ b/mastracode/factory-ui/src/ui/domains/factory/components/BoardCardParts.tsx @@ -1,4 +1,5 @@ import { Badge } from '@mastra/playground-ui/components/Badge'; +import { metadataLabels } from '@mastra/factory/work-items/card-labels'; import { Button, buttonVariants } from '@mastra/playground-ui/components/Button'; import { ScrollArea } from '@mastra/playground-ui/components/ScrollArea'; import { Spinner } from '@mastra/playground-ui/components/Spinner'; @@ -15,7 +16,6 @@ import { HIDDEN_CARD_LABELS, SOURCE_LABELS, metadataLabelColors, - metadataLabels, pullRequestStatusForItem, pullRequestStatusForSource, workItemKey, diff --git a/mastracode/factory-ui/src/ui/domains/factory/components/BoardPropertiesMenu.tsx b/mastracode/factory-ui/src/ui/domains/factory/components/BoardPropertiesMenu.tsx index 35d2346f9fa..9c23dbe3518 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/components/BoardPropertiesMenu.tsx +++ b/mastracode/factory-ui/src/ui/domains/factory/components/BoardPropertiesMenu.tsx @@ -12,8 +12,8 @@ import type { LucideIcon } from 'lucide-react'; import { PropertiesMenu } from '../../../ui/PropertiesMenu'; import { boardFiltersActive, withBoardFilterValues } from '../boardFilters'; -import type { BoardSort } from '../boardOrder'; import { BOARD_SORT_LABELS, boardSortOptions, DEFAULT_BOARD_SORT } from '../boardSort'; +import type { BoardSort } from '../boardSort'; import type { BoardView } from '../hooks/useBoardView'; import { BoardFilterSubmenu } from './BoardFilterSubmenu'; import { boardFilterSummary } from './boardFilterFields'; diff --git a/mastracode/factory-ui/src/ui/domains/factory/components/boardFilterFields.tsx b/mastracode/factory-ui/src/ui/domains/factory/components/boardFilterFields.tsx index cbe560ff23b..17a2c7833bb 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/components/boardFilterFields.tsx +++ b/mastracode/factory-ui/src/ui/domains/factory/components/boardFilterFields.tsx @@ -11,12 +11,13 @@ import { UsersRound, } from 'lucide-react'; import type { LucideIcon } from 'lucide-react'; +import { factoryParticipantId } from '@mastra/factory/work-items/card-people'; +import { PULL_REQUEST_SOURCE_FILTER } from '@mastra/factory/work-items/card-source-filters'; import { boardFilterFieldIds } from '../boardFilters'; import type { BoardFilterFieldId, BoardFilterState } from '../boardFilters'; -import { factoryParticipantId } from '../boardPeople'; import type { BoardParticipant } from '../boardPeople'; -import { BOARD_SOURCE_OPTIONS, PULL_REQUEST_SOURCE_FILTER } from '../boardSourceFilters'; +import { BOARD_SOURCE_OPTIONS } from '../boardSourceFilters'; import type { LinearProject } from '../services/linear'; import { BoardSourceIcon } from './BoardSourceIcon'; diff --git a/mastracode/factory-ui/src/ui/domains/factory/context/__tests__/FeedEventsBoardRefresh.msw.test.tsx b/mastracode/factory-ui/src/ui/domains/factory/context/__tests__/FeedEventsBoardRefresh.msw.test.tsx index 1f77bd509d3..360a4ac9822 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/context/__tests__/FeedEventsBoardRefresh.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/domains/factory/context/__tests__/FeedEventsBoardRefresh.msw.test.tsx @@ -5,6 +5,7 @@ import { act, waitFor } from '@testing-library/react'; import { delay, http, HttpResponse } from 'msw'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { answerBoardPhases, versionedCard } from '../../../../../../e2e/ui/board-reads'; import { pushableFeedStream } from '../../../../../../e2e/ui/feed-stream'; import { server } from '../../../../../../e2e/ui/msw-server'; import { renderHookWithProviders, TEST_BASE_URL, waitForMutationsIdle } from '../../../../../../e2e/ui/render'; @@ -12,9 +13,10 @@ import { queryKeys } from '../../../../../api/keys'; import { useActiveRunResourceIds } from '../../../../../hooks/useActiveRunResources'; import { useFactoryDecisionStatus } from '../../../../../hooks/useFactoryDecisions'; import { + useBoardPhasesQuery, useSessionWorkItemsQuery, + useSidebarWorkItemsQuery, useTransitionWorkItemMutation, - useWorkItemsQuery, workItemActivityQueryOptions, workItemStartersQueryOptions, } from '../../../../../hooks/useWorkItems'; @@ -26,6 +28,7 @@ const PROJECT_ID = 'project-1'; const BOARD_URL = `${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/work-items`; const DECISIONS_URL = `${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/decisions`; const RUNS_URL = '*/api/agent-controller/:controllerId/active-runs'; +const PHASES_URL = `${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/boards/:boardKey/phases`; const FEED_URL = `${TEST_BASE_URL}/web/factory/projects/${PROJECT_ID}/feed-events`; const WITHIN_A_SECOND_MS = 900; const PAST_ONE_REFRESH_GAP_MS = 6_000; @@ -61,8 +64,9 @@ function inner({ children }: { children: React.ReactNode }) { } function watchBoard() { + const cards = useSidebarWorkItemsQuery(PROJECT_ID); return { - cards: useWorkItemsQuery(PROJECT_ID), + cards: { isSuccess: cards.isSuccess, data: cards.data?.workItems }, decisions: useFactoryDecisionStatus(PROJECT_ID, ['pending', 'leased']), running: useActiveRunResourceIds(AGENT_CONTROLLER_ID), move: useTransitionWorkItemMutation(PROJECT_ID), @@ -174,6 +178,51 @@ describe('FeedEventsProvider, on the board', () => { await waitForMutationsIdle(rendered.client); }); + it('lists a card that landed on the board in the phase the board shows, within a second of a frame', async () => { + const stream = pushableFeedStream(PROJECT_ID); + const project = { + workItems: [card('Fix login')], + boards: [{ id: 'work', phases: [{ id: 'intake' }] }], + userId: 'user-1', + }; + let listings = 0; + server.use( + stream.handler, + http.get(PHASES_URL, ({ request, params }) => { + listings += 1; + return answerBoardPhases(request, project, String(params.boardKey)); + }), + http.get(BOARD_URL, ({ request }) => { + const ids = new URL(request.url).searchParams.getAll('workItemId'); + return HttpResponse.json({ + workItems: project.workItems.filter(listed => ids.includes(listed.id)).map(versionedCard), + }); + }), + ); + const rendered = renderHookWithProviders( + () => useBoardPhasesQuery(PROJECT_ID, { board: 'work', sort: 'created-newest', q: '', filters: {}, windows: {} }), + { inner }, + ); + const titlesInIntake = () => { + const snapshot = rendered.result.current.data; + return snapshot?.phases[0]?.ids.map(id => snapshot.workItems.find(held => held.id === id)?.title); + }; + await waitFor(() => expect(stream.open).toBe(true)); + await waitFor(() => expect(titlesInIntake()).toEqual(['Fix login'])); + await advance(rendered.client, PAST_ONE_REFRESH_GAP_MS); + const before = listings; + + project.workItems = [ + ...project.workItems, + { ...card('Fix logout'), id: 'item-2', createdAt: '2030-01-02T00:00:00.000Z' }, + ]; + stream.push(); + await advance(rendered.client, WITHIN_A_SECOND_MS); + + await waitFor(() => expect(titlesInIntake()).toEqual(['Fix logout', 'Fix login'])); + expect(listings).toBe(before + 1); + }); + it('folds a burst of frames into one refresh', async () => { const stream = pushableFeedStream(PROJECT_ID); server.use(stream.handler); @@ -277,7 +326,7 @@ describe('FeedEventsProvider, on the board', () => { server.use(stream.handler); const { requests, board } = boardEndpoints(); const client = createQueryClient(); - client.setQueryData(queryKeys.workItems(PROJECT_ID), boardSnapshot('Fix login')); + client.setQueryData(queryKeys.workItemsWithSessions(PROJECT_ID), boardSnapshot('Fix login')); board.title = 'Fix logout'; const rendered = await renderConnectedBoard(stream, client); @@ -445,9 +494,12 @@ describe('FeedEventsProvider, on a session page', () => { return HttpResponse.json(snapshot); }), ); - // The sidebar reads the whole board on a session page; the header reads the session's cards. + // The sidebar reads every card holding a session; the header reads the session's cards. const rendered = renderHookWithProviders( - () => ({ board: useWorkItemsQuery(PROJECT_ID), session: useSessionWorkItemsQuery(PROJECT_ID, 'session-1') }), + () => ({ + board: useSidebarWorkItemsQuery(PROJECT_ID), + session: useSessionWorkItemsQuery(PROJECT_ID, 'session-1'), + }), { inner }, ); await waitFor(() => expect(stream.open).toBe(true)); diff --git a/mastracode/factory-ui/src/ui/domains/factory/context/__tests__/FeedEventsProvider.msw.test.tsx b/mastracode/factory-ui/src/ui/domains/factory/context/__tests__/FeedEventsProvider.msw.test.tsx index cc9541cb12e..9d805e26a92 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/context/__tests__/FeedEventsProvider.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/domains/factory/context/__tests__/FeedEventsProvider.msw.test.tsx @@ -6,7 +6,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; import { pushableFeedStream } from '../../../../../../e2e/ui/feed-stream'; import { server } from '../../../../../../e2e/ui/msw-server'; import { renderHookWithProviders, TEST_BASE_URL, waitForMutationsIdle } from '../../../../../../e2e/ui/render'; -import { useWorkItemsQuery } from '../../../../../hooks/useWorkItems'; +import { useSidebarWorkItemsQuery } from '../../../../../hooks/useWorkItems'; import { HIDDEN_STREAM_GRACE_MS } from '../../../../lib/hooks/useDocumentVisible'; import { FeedEventsProvider } from '../FeedEventsProvider'; @@ -21,7 +21,7 @@ function inner({ children }: { children: React.ReactNode }) { } function watch() { - return useWorkItemsQuery(PROJECT_ID); + return useSidebarWorkItemsQuery(PROJECT_ID); } function countCardReads(count: () => void) { diff --git a/mastracode/factory-ui/src/ui/domains/factory/hooks/__tests__/useBoardIntake.msw.test.tsx b/mastracode/factory-ui/src/ui/domains/factory/hooks/__tests__/useBoardIntake.msw.test.tsx index 349ff7ac3eb..b246a7255f0 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/hooks/__tests__/useBoardIntake.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/domains/factory/hooks/__tests__/useBoardIntake.msw.test.tsx @@ -4,7 +4,7 @@ * only Work offers items without a card, and a Linear or Jira feed only when * one of that provider's sources is bound to the Factory project being viewed. */ -import { waitFor } from '@testing-library/react'; +import { act, waitFor } from '@testing-library/react'; import { http, HttpResponse } from 'msw'; import { describe, expect, it } from 'vitest'; @@ -69,15 +69,39 @@ function stubIntake( ); } -const renderIntake = ( - factoryProjectId: string, - definition: InstalledBoardInfo = workBoard, - knownSourceKeys = new Set(), - elsewhereSourceKeys?: Set, -) => - renderHookWithProviders(() => - useBoardIntake({ factoryProjectId, repositories: [repository], definition, knownSourceKeys, elsewhereSourceKeys }), +const renderIntake = (factoryProjectId: string, definition: InstalledBoardInfo = workBoard) => + renderHookWithProviders(() => useBoardIntake({ factoryProjectId, repositories: [repository], definition })); + +/** A card the project already holds for a feed item, as the server lists it. */ +const filedCard = (integrationId: string, externalId: string, board: string) => ({ + id: `card-${externalId}`, + orgId: 'org-1', + createdBy: 'user-1', + factoryProjectId: 'factory-1', + board, + externalSource: { integrationId, type: 'issue', externalId }, + parentWorkItemId: null, + title: externalId, + stages: ['intake'], + stageHistory: [], + sessions: {}, + metadata: {}, + triageType: null, + acceptedAt: null, + description: null, + revision: 1, + createdAt: '2026-07-01T00:00:00Z', + updatedAt: '2026-07-01T00:00:00Z', +}); + +/** Answers the lookup of which feed items are already filed with `cards`. */ +function stubFiledCards(factoryProjectId: string, cards: ReturnType[]) { + server.use( + http.get(`${TEST_BASE_URL}/web/factory/projects/${factoryProjectId}/work-items`, () => + HttpResponse.json({ workItems: cards }), + ), ); +} describe('useBoardIntake Linear gating', () => { it('given a source bound to Work on the viewed project, when the board loads, then the Linear feed is offered', async () => { @@ -184,17 +208,191 @@ describe('useBoardIntake project-bound sources', () => { it('counts feed items held back only when their card sits on another board', async () => { stubIntake(bindings, ['factory-1'], issues); - const known = new Set(['linear:REL-1']); + stubFiledCards('factory-1', [filedCard('linear', 'linear:REL-1', 'release')]); - const elsewhere = renderIntake('factory-1', workBoard, known, known); + const elsewhere = renderIntake('factory-1'); await waitFor(() => expect(elsewhere.result.current.candidates).toHaveLength(1)); expect(elsewhere.result.current.alreadyMaterialized).toBe(1); // The same card on this board is already visible in a column; nothing to explain. - const here = renderIntake('factory-1', workBoard, known, new Set()); + stubFiledCards('factory-1', [filedCard('linear', 'linear:REL-1', 'work')]); + const here = renderIntake('factory-1'); await waitFor(() => expect(here.result.current.candidates).toHaveLength(1)); expect(here.result.current.alreadyMaterialized).toBe(0); }); + + /** Answers each filed lookup only once released, with no card filed. */ + function holdFiledLookups() { + const releases: (() => void)[] = []; + server.use( + http.get(`${TEST_BASE_URL}/web/factory/projects/factory-1/work-items`, async () => { + await new Promise(resolve => releases.push(resolve)); + return HttpResponse.json({ workItems: [] }); + }), + ); + return { + held: () => releases.length, + answer: () => releases.splice(0).forEach(release => release()), + }; + } + + describe('while the server has not said which feed items are already filed', () => { + it('offers the next page of a feed only once the items of its first page are shown', async () => { + stubIntake(bindings, ['factory-1'], issues); + server.use( + http.get(`${TEST_BASE_URL}/web/linear/issues`, () => HttpResponse.json({ issues, nextCursor: 'page-2' })), + ); + const filed = holdFiledLookups(); + + const { result } = renderIntake('factory-1'); + + // The feed answered, and its items are held back: the column has nothing to scroll past yet. + await waitFor(() => expect(filed.held()).toBe(1)); + expect(result.current.candidates).toEqual([]); + expect(result.current.isPending).toBe(true); + expect(result.current.feedByColumn.intake?.hasNextPage).toBe(false); + + filed.answer(); + await waitFor(() => expect(result.current.candidates).toHaveLength(2)); + expect(result.current.isPending).toBe(false); + expect(result.current.feedByColumn.intake?.hasNextPage).toBe(true); + }); + + it('keeps a later page loading until its items are known, with the earlier ones still listed', async () => { + stubIntake(bindings, ['factory-1'], issues); + server.use( + http.get(`${TEST_BASE_URL}/web/linear/issues`, ({ request }) => + new URL(request.url).searchParams.has('after') + ? HttpResponse.json({ issues: [linearIssue('ENG-2', 'proj-1')], nextCursor: null }) + : HttpResponse.json({ issues, nextCursor: 'page-2' }), + ), + ); + const { result } = renderIntake('factory-1'); + await waitFor(() => expect(result.current.candidates).toHaveLength(2)); + + const filed = holdFiledLookups(); + await act(async () => { + await result.current.feedByColumn.intake?.fetchNextPage(); + }); + await waitFor(() => expect(filed.held()).toBe(1)); + expect(result.current.candidates).toHaveLength(2); + expect(result.current.isPending).toBe(false); + expect(result.current.feedByColumn.intake?.isFetchingNextPage).toBe(true); + + filed.answer(); + await waitFor(() => expect(result.current.candidates).toHaveLength(3)); + expect(result.current.feedByColumn.intake?.isFetchingNextPage).toBe(false); + }); + }); + + it('leaves a feed as it is shown while a board refresh asks again which of its items are filed', async () => { + stubIntake(bindings, ['factory-1'], issues); + server.use( + http.get(`${TEST_BASE_URL}/web/linear/issues`, () => HttpResponse.json({ issues, nextCursor: 'page-2' })), + ); + const { result, client } = renderIntake('factory-1'); + await waitFor(() => expect(result.current.candidates).toHaveLength(2)); + + const filed = holdFiledLookups(); + // What a feed frame does to every read of the project's cards. + act(() => void client.invalidateQueries({ queryKey: queryKeys.workItems('factory-1') })); + await waitFor(() => expect(filed.held()).toBe(1)); + + // The items are known already: no row leaves, no page reads as loading, the next one stays on offer. + expect(result.current.candidates).toHaveLength(2); + expect(result.current.isPending).toBe(false); + expect(result.current.feedByColumn.intake?.isFetchingNextPage).toBe(false); + expect(result.current.feedByColumn.intake?.hasNextPage).toBe(true); + + filed.answer(); + await waitFor(() => expect(client.isFetching()).toBe(0)); + expect(result.current.candidates).toHaveLength(2); + }); + + it('reports a failed filed lookup as a failed feed, not an empty column, and asks again on retry', async () => { + stubIntake(bindings, ['factory-1'], issues); + server.use( + http.get(`${TEST_BASE_URL}/web/factory/projects/factory-1/work-items`, () => + HttpResponse.json({ error: 'nope' }, { status: 500 }), + ), + ); + + const { result } = renderIntake('factory-1'); + + await waitFor(() => expect(result.current.feedByColumn.intake?.error).toBeInstanceOf(Error)); + expect(result.current.candidates).toEqual([]); + expect(result.current.isPending).toBe(false); + + stubFiledCards('factory-1', []); + await act(async () => { + await result.current.feedByColumn.intake?.refetch(); + }); + await waitFor(() => expect(result.current.candidates).toHaveLength(2)); + expect(result.current.feedByColumn.intake?.error).toBeNull(); + }); + + it('shows the one source picked when the lookup of a source the view hides fails, and looks nothing up for that source', async () => { + stubIntake(bindings, ['factory-1'], issues); + const lookedUp: string[] = []; + server.use( + http.get(`${TEST_BASE_URL}/web/intake/config`, () => + HttpResponse.json({ + config: { + github: { enabled: true, sourceIds: ['acme/app'] }, + linear: { enabled: true, sourceIds: ['proj-1', 'proj-2'] }, + }, + }), + ), + http.get(`${TEST_BASE_URL}/web/github/projects/repo-1/issues`, () => + HttpResponse.json({ + issues: [ + { + number: 7, + title: 'Issue 7', + url: 'https://github.com/acme/app/issues/7', + author: 'octocat', + labels: [], + comments: 0, + createdAt: '2026-07-01T00:00:00Z', + updatedAt: '2026-07-02T00:00:00Z', + }, + ], + nextCursor: null, + }), + ), + // The server answers for Linear items and fails for GitHub ones. + http.get(`${TEST_BASE_URL}/web/factory/projects/factory-1/work-items`, ({ request }) => { + const sources = new URL(request.url).searchParams.getAll('source'); + lookedUp.push(...sources); + if (sources.some(source => source.includes('github'))) { + return HttpResponse.json({ error: 'nope' }, { status: 500 }); + } + return HttpResponse.json({ workItems: [] }); + }), + ); + + const { result, client } = renderHookWithProviders(() => + useBoardIntake({ + factoryProjectId: 'factory-1', + repositories: [repository], + definition: workBoard, + sourceFilters: { source: new Set(['linear']), linearProject: new Set() }, + }), + ); + + // The hidden GitHub feed is read all the same: the person filters name its people. + await waitFor(() => + expect(result.current.participantCandidates).toContainEqual(expect.objectContaining({ source: 'github-issue' })), + ); + await waitFor(() => expect(result.current.candidates).toHaveLength(2)); + await waitFor(() => expect(client.isFetching()).toBe(0)); + + expect(result.current.candidates.map(candidate => candidate.sourceKey)).toEqual(['linear:ENG-1', 'linear:REL-1']); + expect(result.current.feedByColumn.intake?.error).toBeNull(); + expect(result.current.isPending).toBe(false); + expect(lookedUp.filter(source => source.includes('github'))).toEqual([]); + expect(lookedUp).toContain('linear:ENG-1'); + }); }); describe('useBoardIntake GitLab routing', () => { @@ -232,7 +430,6 @@ describe('useBoardIntake GitLab routing', () => { factoryProjectId: 'factory-1', repositories: [{ ...repository, provider: 'gitlab' }], definition: workBoard, - knownSourceKeys: new Set(), }), ); @@ -278,7 +475,6 @@ describe('useBoardIntake GitLab routing', () => { factoryProjectId: 'factory-1', repositories: [{ ...repository, provider: 'gitlab' }], definition: workBoard, - knownSourceKeys: new Set(), }), ); @@ -595,7 +791,8 @@ describe('useBoardIntake Jira gating', () => { it('given the issue is already a card, when candidates map, then the known source key is dropped', async () => { stubJiraIntake([workBinding]); - const { result } = renderIntake('factory-1', workBoard, new Set(['jira-issue-acme-eng-42'])); + stubFiledCards('factory-1', [filedCard('jira', 'jira-issue-acme-eng-42', 'work')]); + const { result } = renderIntake('factory-1'); await waitFor(() => expect(result.current.participantCandidates).toHaveLength(1)); expect(result.current.candidates).toEqual([]); @@ -743,7 +940,6 @@ describe('useBoardIntake across linked repositories', () => { factoryProjectId: 'factory-1', repositories, definition: workBoard, - knownSourceKeys: new Set(), }), ); @@ -762,7 +958,6 @@ describe('useBoardIntake across linked repositories', () => { factoryProjectId: 'factory-1', repositories, definition: workBoard, - knownSourceKeys: new Set(), }), ); @@ -781,12 +976,12 @@ describe('useBoardIntake across linked repositories', () => { it('drops a second repository candidate that is already a card without hiding the first repository one', async () => { stubRepositories([]); + stubFiledCards('factory-1', [filedCard('github', 'github:2:issue:5', 'work')]); const { result } = renderHookWithProviders(() => useBoardIntake({ factoryProjectId: 'factory-1', repositories, definition: workBoard, - knownSourceKeys: new Set(['github:2:issue:5']), }), ); diff --git a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardIntake.ts b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardIntake.ts index d288724c154..9ea8732a891 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardIntake.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardIntake.ts @@ -1,6 +1,13 @@ import { DEFAULT_BOARD_ID } from '@mastra/factory/boards/default-board'; import { AUTO_TRIAGED_LABEL } from '@mastra/factory/rules/types'; +import { pickedBoardSources, PULL_REQUEST_SOURCE_FILTER } from '@mastra/factory/work-items/card-source-filters'; +import { useQueries, useQueryClient } from '@tanstack/react-query'; +import type { UseQueryResult } from '@tanstack/react-query'; +import { useApiConfig } from '../../../../api/config'; +import { queryKeys } from '../../../../api/keys'; import { useProjectIssuesQuery, useProjectPullRequestsQuery } from '../../../../hooks/useFactoryData'; +import { filedFromQueryOptions } from '../../../../hooks/useWorkItems'; +import type { FiledFromAnswer } from '../../../../hooks/useWorkItems'; import { useGitLabIssuesQuery, useGitLabMergeRequestsQuery, @@ -23,8 +30,8 @@ import { } from '../boardCandidates'; import type { BoardCandidate, IntakeFeed, IntakeSource } from '../boardCandidates'; import type { BoardFilterState } from '../boardFilters'; -import { isPersistedCandidate } from '../boardItems'; -import { pickedBoardSources, PULL_REQUEST_SOURCE_FILTER } from '../boardSourceFilters'; +import { isPersistedCandidate, persistedSourceKeys } from '../boardItems'; +import { itemBoard } from '../boardStages'; import type { IntakeSourceBinding } from '../services/intake'; import type { InstalledBoardInfo } from '../../../../api/types'; import type { BoardStageId } from '../stages'; @@ -38,7 +45,6 @@ import type { BoardStageId } from '../stages'; * yet: GitHub issues from the selected repositories, the linked repositories' * pull requests, and the issues of provider sources bound to the project. */ -const EMPTY_KEYS: ReadonlySet = new Set(); const NO_REPOSITORIES: readonly string[] = []; const INTAKE_CARD_SOURCES: Record = { @@ -100,23 +106,70 @@ function combineIntakeFeeds(feeds: readonly (IntakeFeed & { isPending: boolean } }; } +/** The most feed items one filed lookup covers: each is asked by its source id and by its URL, a hundred values at most. */ +const CANDIDATES_PER_LOOKUP = 50; + +/** + * What each filed lookup asks about: every feed in runs of items, so a page added to one feed + * leaves the lookups of the others, and of its own earlier runs, as they were. + */ +function filedLookupSources(feeds: readonly (readonly BoardCandidate[])[]): string[][] { + const lookups: string[][] = []; + for (const feed of feeds) { + for (let start = 0; start < feed.length; start += CANDIDATES_PER_LOOKUP) { + lookups.push( + feed + .slice(start, start + CANDIDATES_PER_LOOKUP) + .flatMap(candidate => [candidate.sourceKey, candidate.url]) + .filter(Boolean), + ); + } + } + return lookups; +} + +/** + * A feed as its column shows it. Its items are held back until the server says which are already + * filed, so a page counts as loaded only then: otherwise the end of the column is in view over the + * items held back, and asks for the next page. A lookup that failed fails the feed, or the column + * would read as an empty backlog. + */ +function feedOnceItemsAreLookedUp( + feed: IntakeFeed & { isPending: boolean }, + lookups: readonly UseQueryResult[], +): IntakeFeed & { isPending: boolean } { + const failed = lookups.find(lookup => lookup.isError); + if (failed && !feed.error) { + return { + ...feed, + isPending: false, + error: failed.error, + isFetchNextPageError: false, + refetch: () => Promise.all(lookups.filter(lookup => lookup.isError).map(lookup => lookup.refetch())), + }; + } + // A lookup showing what was answered for a shorter run still waits for the items added to it. + const awaited = lookups.some(lookup => lookup.isFetching && (lookup.isPending || lookup.isPlaceholderData)); + if (!awaited) return feed; + // Nothing answered yet: the column has no item to show, as while the first page loads. + if (lookups.every(lookup => !lookup.data)) return { ...feed, isPending: true, hasNextPage: false }; + return { ...feed, isFetchingNextPage: true }; +} + export function useBoardIntake({ factoryProjectId, repositories, definition, - knownSourceKeys, - elsewhereSourceKeys = EMPTY_KEYS, sourceFilters, }: { factoryProjectId: string; /** Every linked repository; the first decides between GitHub and GitLab review feeds. */ repositories: readonly LinkedRepositoryPayload[]; definition: InstalledBoardInfo; - knownSourceKeys: ReadonlySet; - /** Subset of `knownSourceKeys` whose card lives on another board. */ - elsewhereSourceKeys?: ReadonlySet; sourceFilters?: Pick; }) { + const { baseUrl } = useApiConfig(); + const queryClient = useQueryClient(); const kind = definition.id; const defaultBoard = kind === DEFAULT_BOARD_ID; const browsesPullRequests = defaultBoard; @@ -299,10 +352,37 @@ export function useBoardIntake({ if (source !== 'github' || !triageColumn) return initialCandidates; return [...initialCandidates, ...(triageIssues.data ?? []).map(issueCandidate)]; }); - // A source materializes once per Factory, so items that already have a card - // are held back. Only those carded on another board get counted: a card on - // this board is visible in a column, so it needs no explanation. - const candidates = browsedCandidates.filter(candidate => !isPersistedCandidate(knownSourceKeys, candidate)); + // A source materializes once per Factory, so items that already have a card are held back. The + // server says which ones do, for the feed items alone: the board lists only the first cards of + // each column. An item waits for that answer, or it would flash as new before leaving. A source + // the view hides shows no item, so nothing is asked for it and its answer holds no feed back. + const initialFeedLookups = filedLookupSources( + browsedSources.map(source => + participantCandidates.filter(candidate => candidate.source === INTAKE_CARD_SOURCES[source]), + ), + ); + const triageFeedLookups = filedLookupSources([(triageIssues.data ?? []).map(issueCandidate)]); + const filedLookups = useQueries({ + queries: [...initialFeedLookups, ...triageFeedLookups].map(sources => ({ + ...filedFromQueryOptions(baseUrl, factoryProjectId, sources), + // A feed page added to a run asks again: what was answered for the shorter run holds meanwhile. + placeholderData: () => + queryClient + .getQueriesData({ queryKey: queryKeys.workItemsFiledFromAny(factoryProjectId) }) + .flatMap(([, answer]) => (answer ? [answer] : [])) + .find(answer => answer.sources.every(source => sources.includes(source))), + })), + }); + const filedAnswers = filedLookups.flatMap(lookup => (lookup.data ? [lookup.data] : [])); + const lookedUpSources = new Set(filedAnswers.flatMap(answer => answer.sources)); + const filedCards = filedAnswers.flatMap(answer => answer.workItems); + const knownSourceKeys = persistedSourceKeys(filedCards); + // Only those carded on another board get counted: a card on this board is visible in a column, + // so it needs no explanation. + const elsewhereSourceKeys = persistedSourceKeys(filedCards.filter(card => itemBoard(card) !== kind)); + const candidates = browsedCandidates.filter( + candidate => lookedUpSources.has(candidate.sourceKey) && !isPersistedCandidate(knownSourceKeys, candidate), + ); const alreadyMaterialized = browsedCandidates.filter(candidate => isPersistedCandidate(elsewhereSourceKeys, candidate), ).length; @@ -321,7 +401,7 @@ export function useBoardIntake({ incidentio: incidentioFeed, }; const failedSource = browsedSources.find(source => browsed[source].error); - const feed = intakeRoutesFailed + const browsedFeed = intakeRoutesFailed ? { error: intakeRoutesQuery.error, isPending: false, @@ -329,10 +409,12 @@ export function useBoardIntake({ refetch: () => intakeRoutesQuery.refetch(), } : combineIntakeFeeds(browsedSources.map(source => browsed[source])); + const feed = browsedFeed && feedOnceItemsAreLookedUp(browsedFeed, filedLookups.slice(0, initialFeedLookups.length)); // Triage is fed by its own labelled query, so it fails (and retries) on its own. + const triageFeed = feedOnceItemsAreLookedUp(triageIssues, filedLookups.slice(initialFeedLookups.length)); const feedByColumn: Partial> = { [initialPhase]: feed, - ...(triageColumn && browsesGithub ? { triage: triageIssues } : {}), + ...(triageColumn && browsesGithub ? { triage: triageFeed } : {}), }; // Keep an unresolved board pending while discovering its routed sources. @@ -354,8 +436,10 @@ export function useBoardIntake({ candidates, alreadyMaterialized, participantCandidates, + /** The sources of the browsed feeds' items already filed as a card, on this board or another. */ + knownSourceKeys, feedByColumn, isPending, - isTriagePending: triageColumn && browsesGithub && triageIssues.isPending, + isTriagePending: triageColumn && browsesGithub && triageFeed.isPending, }; } diff --git a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardItems.ts b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardItems.ts index 76df440df91..f72c0ee0ed6 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardItems.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardItems.ts @@ -1,5 +1,5 @@ import { boardLoop, boardOf } from '../boardFlow'; -import { useMemo, useRef, useState } from 'react'; +import { useRef, useState } from 'react'; import { useBoardCatalog } from '../../../../hooks/useBoardCatalog'; import { @@ -7,11 +7,9 @@ import { useTransitionWorkItemMutation, useUpdateWorkItemMutation, useUpsertWorkItemMutation, - useWorkItemsQuery, } from '../../../../hooks/useWorkItems'; import type { DragPayload } from '../boardDrag'; -import { persistedSourceKeys } from '../boardItems'; -import { belongsToBoard, itemBoard, pullRequestMayEnter } from '../boardStages'; +import { itemBoard, pullRequestMayEnter } from '../boardStages'; import type { BoardKind } from '../boardStages'; import { inferredParentWorkItemId } from '../services/relationships'; import type { WorkItem } from '../services/workItems'; @@ -23,23 +21,25 @@ interface MoveOptions { repositorySlug?: string; } -/** The board's persisted cards: the query behind them and the moves that rewrite them. */ +/** The moves that rewrite a board's persisted cards, for a caller that holds the cards it acts on. */ export function useBoardItems({ factoryProjectId, kind, currentUserId, onFailure, - items: given, + items: all, }: { factoryProjectId: string | undefined; kind: BoardKind; - /** The cards to act on, from a caller that holds a few of them and must not download the board, e.g. search. */ - items?: readonly WorkItem[]; + /** + * The cards to act on: the ones the caller shows, and the ones holding a session, which a + * dropped pull request finds its issue among. + */ + items: readonly WorkItem[]; currentUserId?: string; /** Where a failure goes when no card is on screen to carry it, e.g. the search palette. */ onFailure?: (message: string) => void; }) { - const items = useWorkItemsQuery(given ? undefined : factoryProjectId); const catalog = useBoardCatalog(factoryProjectId); const upsert = useUpsertWorkItemMutation(factoryProjectId); const update = useUpdateWorkItemMutation(factoryProjectId); @@ -49,12 +49,6 @@ export function useBoardItems({ const [dropError, setDropError] = useState(); const movingRef = useRef>(new Set()); - const all = useMemo(() => given ?? items.data ?? [], [given, items.data]); - const knownSourceKeys = useMemo(() => persistedSourceKeys(all), [all]); - // Sources whose card sits on another board: the only withheld feed items worth explaining. - const elsewhereSourceKeys = persistedSourceKeys(all.filter(item => !belongsToBoard(item, kind))); - const visible = all.filter(item => belongsToBoard(item, kind)); - const requestTransition = (item: WorkItem, toStage: string, options: MoveOptions = {}, onSettled?: () => void) => { setTransitionReasons(current => { if (!(item.id in current)) return current; @@ -121,7 +115,7 @@ export function useBoardItems({ const handleDrop = (payload: DragPayload, toStage: BoardStageId, cause = 'board_drag') => { if (payload.kind === 'work-item') { const item = all.find(candidate => candidate.id === payload.id); - if (!item || !belongsToBoard(item, kind) || payload.fromStage === toStage) return; + if (!item || itemBoard(item) !== kind || payload.fromStage === toStage) return; move(payload.id, toStage, { cause }); return; } @@ -157,16 +151,9 @@ export function useBoardItems({ }; return { - all, - visible, - knownSourceKeys, - elsewhereSourceKeys, - isPending: items.isPending, - error: items.isError ? items.error : undefined, mutationError: [upsert, transition, remove].find(mutation => mutation.isError)?.error ?? dropError, evaluatingStages: new Map(transition.pendingTransitions.map(({ itemId, stage }) => [itemId, stage])), transitionReasons, - refetch: items.refetch, move, remove: (id: string) => remove.mutate(id), handleDrop, diff --git a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardRuns.ts b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardRuns.ts index 34e784a8cda..c4f283a6084 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardRuns.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardRuns.ts @@ -2,29 +2,20 @@ import { toast } from '@mastra/playground-ui/components/Toaster'; import { useRef, useState } from 'react'; import { useNavigate } from 'react-router'; +import { useApiConfig } from '../../../../api/config'; import { useStartFactoryRun } from '../../../../hooks/useStartFactoryRun'; import { useCardRepositorySlug } from './useCardRepositorySlug'; import { itemSessionSpec, itemThreadSession } from '../boardItems'; import { repositoryMatchesCardSource } from '../boardRepository'; import type { LinkedRepositoryPayload } from '../../workspaces/services/github'; +import { listWorkItems } from '../services/workItems'; import type { WorkItem, WorkItemSessionRef } from '../services/workItems'; const PREPARING_SESSION_LABEL = 'Preparing session…'; /** Opening the chat session a card carries, and minting one when it has none yet. */ -export function useBoardRuns({ - factoryProjectId, - refetchItems, -}: { - factoryProjectId: string; - /** - * A fresh read of the cards a click can land on. It is given the id of the card clicked, and may - * send that card alone: the card is taken as deleted when the read succeeds without it. - */ - refetchItems: ( - itemId: string, - ) => Promise<{ isSuccess: true; data: WorkItem[] } | { isSuccess: false; error: unknown }>; -}) { +export function useBoardRuns({ factoryProjectId }: { factoryProjectId: string }) { + const { baseUrl } = useApiConfig(); const { start, startingItemIds, enabled, repositories } = useStartFactoryRun(); const repositorySlugFor = useCardRepositorySlug(repositories); const navigate = useNavigate(); @@ -65,16 +56,18 @@ export function useBoardRuns({ navigate(`/factories/${factoryProjectId}/workspaces/${session.sessionId}/threads/${session.threadId}`); }; - // Refetch failures here used to be silent: an expired auth cookie made every - // board click a no-op with no feedback. Toast so the click never dies quietly. + // The clicked card alone, read fresh: it may have gained a session since it was listed, or been + // deleted. A failed read used to be silent: an expired auth cookie made every board click a + // no-op with no feedback. Toast so the click never dies quietly. const refreshItem = async (itemId: string) => { - const refreshedItems = await refetchItems(itemId); - if (!refreshedItems.isSuccess) { - const cause = refreshedItems.error; + let cards: WorkItem[]; + try { + cards = (await listWorkItems(baseUrl, factoryProjectId, undefined, { workItemId: [itemId] })).workItems; + } catch (cause) { toast.error(cause instanceof Error ? cause.message : 'Failed to refresh the board. Try reloading the page.'); return; } - const item = refreshedItems.data.find(candidate => candidate.id === itemId); + const item = cards.find(candidate => candidate.id === itemId); if (!item) { toast.error('This card no longer exists. The board may be out of date.'); return; diff --git a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardView.ts b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardView.ts index cfddaeba34b..6031bb59f85 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardView.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardView.ts @@ -13,16 +13,16 @@ import { import type { BoardFilterState } from '../boardFilters'; import { boardLayoutFromParams, boardLayoutParams } from '../boardLayout'; import type { BoardLayout } from '../boardLayout'; -import type { BoardSort } from '../boardOrder'; import { withPeopleFolded, withPeopleUnfolded } from '../boardPeople'; import type { PersonIdentity } from '../boardPeople'; import { BOARD_VIEW_QUERY, boardViewSettingsSchema, savedBoardViewsStorageKey } from '../boardSavedViews'; import type { BoardViewSettings } from '../boardSavedViews'; import { boardSortFromParams, boardSortParams, DEFAULT_BOARD_SORT } from '../boardSort'; +import type { BoardSort } from '../boardSort'; import type { BoardKind } from '../boardStages'; import { saveBoardView } from '../services/boardViews'; -const BOARD_SEARCH_QUERY = 'search'; +export const BOARD_SEARCH_QUERY = 'search'; export interface BoardView { searchParams: URLSearchParams; diff --git a/mastracode/factory-ui/src/ui/domains/factory/hooks/useFactoryActivity.ts b/mastracode/factory-ui/src/ui/domains/factory/hooks/useFactoryActivity.ts index efd9168f9ff..3da896885be 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/hooks/useFactoryActivity.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/hooks/useFactoryActivity.ts @@ -1,12 +1,10 @@ import { useQuery } from '@tanstack/react-query'; -import { useLocation } from 'react-router'; import { useApiConfig } from '../../../../api/config'; import type { WorkItemActivity } from '../../../../api/types'; import { useActiveRunResourceIds } from '../../../../hooks/useActiveRunResources'; import { useSidebarWorkItemsQuery, workItemActivityQueryOptions } from '../../../../hooks/useWorkItems'; import { AGENT_CONTROLLER_ID } from '../../chat/services/constants'; -import { pageLoadsBoard } from '../pageLoadsBoard'; import { activityDepth, liveSessionCounts, periodActivity } from '../periodActivity'; import type { ActivityPeriod, RunStarts } from '../periodActivity'; import { useRunStarts } from './useRunStarts'; @@ -21,7 +19,6 @@ const NO_CARD_TIMES: WorkItemActivity = { total: 0, createdAt: [], doneAt: [] }; export function useFactoryActivity(factoryId: string, period: ActivityPeriod) { const { baseUrl } = useApiConfig(); - const { pathname } = useLocation(); const depth = activityDepth(period); const week = useQuery({ ...workItemActivityQueryOptions(baseUrl, factoryId, 'week'), enabled: depth === 'week' }); const month = useQuery({ ...workItemActivityQueryOptions(baseUrl, factoryId, 'month'), enabled: depth === 'month' }); @@ -33,7 +30,7 @@ export function useFactoryActivity(factoryId: string, period: ActivityPeriod) { const runs = useRunStarts(factoryId, period); const running = useActiveRunResourceIds(AGENT_CONTROLLER_ID); // Only a card holding a session can be working or waiting, and the sidebar already reads those. - const sessionCards = useSidebarWorkItemsQuery(factoryId, pageLoadsBoard(pathname)).data; + const sessionCards = useSidebarWorkItemsQuery(factoryId).data; const activity = periodActivity({ period, now: Math.max(shown.dataUpdatedAt, runs.dataUpdatedAt), diff --git a/mastracode/factory-ui/src/ui/domains/factory/hooks/useItemSessionStatuses.ts b/mastracode/factory-ui/src/ui/domains/factory/hooks/useItemSessionStatuses.ts index a62580b8125..44280a8b8ab 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/hooks/useItemSessionStatuses.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/hooks/useItemSessionStatuses.ts @@ -1,5 +1,4 @@ import { useActiveRunResources } from '../../../../hooks/useActiveRunResources'; -import { useParkedSessions } from '../../../../hooks/useWorkItems'; import { allSessionRows, useWorkspacesQuery } from '../../../../hooks/useWorkspaces'; import { AGENT_CONTROLLER_ID } from '../../chat/services/constants'; import { sessionRowStatus } from '../../workspaces/services/sessionStatus'; @@ -15,17 +14,20 @@ export function useItemSessionStatuses({ factoryProjectId, projectRepositoryId, items, + parkedSessionIds: parked, }: { factoryProjectId: string; projectRepositoryId: string; items: readonly WorkItem[]; + /** The sessions parked on a plan or a question, read with `items` so a card and its marker agree. */ + parkedSessionIds: readonly string[]; }): ReadonlyMap { const boundSessionIds = items.flatMap(item => Object.values(item.sessions ?? {}).map(ref => ref.sessionId)); const runningBySessionId = useActiveRunResources({ agentControllerId: AGENT_CONTROLLER_ID, resourceIds: boundSessionIds, }); - const parkedSessionIds = useParkedSessions(factoryProjectId); + const parkedSessionIds = new Set(parked); const workspaces = useWorkspacesQuery(factoryProjectId); const materializingSessionIds = new Set( allSessionRows(workspaces.data) diff --git a/mastracode/factory-ui/src/ui/domains/factory/pageLoadsBoard.ts b/mastracode/factory-ui/src/ui/domains/factory/pageLoadsBoard.ts deleted file mode 100644 index e7dc9d21bcb..00000000000 --- a/mastracode/factory-ui/src/ui/domains/factory/pageLoadsBoard.ts +++ /dev/null @@ -1,4 +0,0 @@ -/** Pages that load the whole board themselves: the boards. */ -export function pageLoadsBoard(pathname: string) { - return /^\/factories\/[^/]+\/(?:work|review|boards\/[^/]+)\/?$/.test(pathname); -} diff --git a/mastracode/factory-ui/src/ui/domains/factory/services/workItems.test.ts b/mastracode/factory-ui/src/ui/domains/factory/services/workItems.test.ts index f6818307523..6ba9f78f255 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/services/workItems.test.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/services/workItems.test.ts @@ -36,7 +36,7 @@ describe('Factory work item service boundary', () => { it('maps provider-neutral server work items to the board source model', async () => { vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ workItems: [wireItem] }))); - const [item] = (await listWorkItems('', 'project-1')).workItems; + const [item] = (await listWorkItems('', 'project-1', undefined, { workItemId: ['item-1'] })).workItems; expect(item).toMatchObject({ githubProjectId: 'project-1', @@ -66,7 +66,7 @@ describe('Factory work item service boundary', () => { const externalSource = { integrationId: 'slack', type: 'slack-thread', ...slackSource }; vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ workItems: [{ ...wireItem, externalSource }] }))); - const [item] = (await listWorkItems('', 'project-1')).workItems; + const [item] = (await listWorkItems('', 'project-1', undefined, { workItemId: ['item-1'] })).workItems; expect(item).toMatchObject({ source: 'slack-thread', sourceKey: slackSource.externalId, url }); }); @@ -80,10 +80,21 @@ describe('Factory work item service boundary', () => { }; vi.stubGlobal('fetch', vi.fn().mockResolvedValue(jsonResponse({ workItems: [{ ...wireItem, externalSource }] }))); - const [item] = (await listWorkItems('', 'project-1')).workItems; + const [item] = (await listWorkItems('', 'project-1', undefined, { workItemId: ['item-1'] })).workItems; expect(item).toMatchObject({ source: 'gitlab-pr', sourceKey: externalSource.externalId, url: externalSource.url }); }); + it.each([{ workItemId: [] }, { source: [] }])( + 'answers %o with no card and no request, since sent bare it would read the whole project', + async none => { + const fetchMock = vi.fn().mockResolvedValue(jsonResponse({ workItems: [wireItem] })); + vi.stubGlobal('fetch', fetchMock); + + expect((await listWorkItems('', 'project-1', undefined, none)).workItems).toEqual([]); + expect(fetchMock).not.toHaveBeenCalled(); + }, + ); + it('sends provider-neutral external source data when creating a board item', async () => { const fetchMock = vi.fn().mockResolvedValue(jsonResponse({ workItem: wireItem })); vi.stubGlobal('fetch', fetchMock); diff --git a/mastracode/factory-ui/src/ui/domains/factory/services/workItems.ts b/mastracode/factory-ui/src/ui/domains/factory/services/workItems.ts index b60cc1492e8..43fa4792ce7 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/services/workItems.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/services/workItems.ts @@ -9,7 +9,14 @@ import type { FactoryRuleStage, FactoryTriageType } from '@mastra/factory/rules/types'; import type { WorkItemRow } from '@mastra/factory/storage/domains/work-items/work-item-schema'; -import type { WorkItemActivity, WorkItemListResponse, WorkItemStarters } from '../../../../api/types'; +import type { + WorkItemActivity, + BoardPhasesRequest, + BoardPhasesResponse, + WorkItemFilterOptions, + WorkItemListResponse, + WorkItemStarters, +} from '../../../../api/types'; import { requestJson } from './request'; export type WorkItemSource = @@ -135,8 +142,11 @@ export interface WorkItem { revision: number; createdAt: string; updatedAt: string; - /** When the card last changed in any way, which `boardCheck` reads. */ - changedAt?: string | null; + /** + * What the server names this body by: the board read names each card with the version of the + * body it would send. A card a write answered, or one changed here, has none until it is read again. + */ + version?: string; } /** Session ref as sent by the client — `startedBy` is stamped server-side. */ @@ -303,55 +313,94 @@ export interface BoardSnapshot { parkedSessionIds: string[]; /** How many cards matched a `started: 'false'` read, of which `workItems` holds the first. */ total?: number; - /** Names this read of the whole board to the server. Kept with the cards it was read with. */ - cursor?: string; } -/** A board read as the server answers it. With `removedIds` it holds only what moved since the cursor sent. */ -export type BoardRead = BoardSnapshot & Pick; - /** - * List the org's work items for a Factory project: the whole board, or with `only` a part of it. + * List a part of the org's work items for a Factory project: never the whole of them. * `sessionId` and `scope: 'sessions'` ask for the cards holding that session or any session, with * the cards related to them; `started: 'false'` for the most recently updated cards holding no * session whose text has every word of `q`; `source` for the cards filed from those source ids or * URLs; `workItemId` for the cards with those ids. - * With `since`, the cursor of a board already held, a server that can sends only what moved. */ export async function listWorkItems( baseUrl: string, factoryProjectId: string, - signal?: AbortSignal, - only?: + signal: AbortSignal | undefined, + only: | { sessionId: string } | { scope: 'sessions' } | { started: 'false'; q: string } | { source: string[] } - | { workItemId: string[] } - | { since: string }, -): Promise { - const params = - only && - new URLSearchParams( - 'source' in only - ? only.source.map(source => ['source', source]) - : 'workItemId' in only - ? only.workItemId.map(id => ['workItemId', id]) - : only, - ); - const { workItems, runningSessionIds, parkedSessionIds, ...rest } = await requestJson< + | { workItemId: string[] }, +): Promise { + const params = new URLSearchParams( + 'source' in only + ? only.source.map(source => ['source', source]) + : 'workItemId' in only + ? only.workItemId.map(id => ['workItemId', id]) + : only, + ); + // No id and no source asked for: no card. Sent bare, the request would read the whole project. + if (params.size === 0) return { workItems: [], runningSessionIds: [], parkedSessionIds: [] }; + const { workItems, runningSessionIds, parkedSessionIds, total } = await requestJson< Partial> & { workItems: WireWorkItem[] } - >(`${baseUrl}/web/factory/projects/${encodeURIComponent(factoryProjectId)}/work-items${params ? `?${params}` : ''}`, { - signal, - }); + >(`${baseUrl}/web/factory/projects/${encodeURIComponent(factoryProjectId)}/work-items?${params}`, { signal }); return { - ...rest, workItems: workItems.map(fromWireWorkItem), runningSessionIds: runningSessionIds ?? [], parkedSessionIds: parkedSessionIds ?? [], + ...(total === undefined ? {} : { total }), }; } +/** The board read's answer. It holds the cards' bodies only when they were asked for. */ +export interface BoardPhasesAnswer extends Omit { + workItems?: WorkItem[]; +} + +/** + * Which cards each phase of a board view lists, in the view's order, and how many match. + * `cards` also asks for the body of every card the answer names. + */ +export async function fetchBoardPhases( + baseUrl: string, + factoryProjectId: string, + request: BoardPhasesRequest, + cards: boolean, + signal?: AbortSignal, +): Promise { + // One order of parameters per view: the browser revalidates an address it has already read. + const params = new URLSearchParams({ sort: request.sort }); + if (request.q) params.set('q', request.q); + for (const [filter, picked] of Object.entries(request.filters).sort(([left], [right]) => left.localeCompare(right))) { + for (const value of picked) params.append(filter, value); + } + for (const [phase, count] of Object.entries(request.windows).sort(([left], [right]) => left.localeCompare(right))) { + params.append('window', `${phase}:${count}`); + } + if (request.item) params.set('item', request.item); + if (cards) params.set('cards', 'true'); + const { workItems, ...answer } = await requestJson< + Omit & { workItems?: WireWorkItem[] } + >( + `${baseUrl}/web/factory/projects/${encodeURIComponent(factoryProjectId)}/boards/${encodeURIComponent(request.board)}/phases?${params}`, + { signal }, + ); + return workItems ? { ...answer, workItems: workItems.map(fromWireWorkItem) } : answer; +} + +/** The labels and people the project's cards can be filtered by. */ +export function fetchWorkItemFilterOptions( + baseUrl: string, + factoryProjectId: string, + signal?: AbortSignal, +): Promise { + return requestJson( + `${baseUrl}/web/factory/projects/${encodeURIComponent(factoryProjectId)}/work-items/filter-options`, + { signal }, + ); +} + /** What the draft page's starter buttons count on the project's default board. */ export function fetchWorkItemStarters( baseUrl: string, diff --git a/mastracode/factory-ui/src/ui/domains/factory/workItemActivity.ts b/mastracode/factory-ui/src/ui/domains/factory/workItemActivity.ts index 95c88fb4709..b20036ac964 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/workItemActivity.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/workItemActivity.ts @@ -165,15 +165,6 @@ function latestStageWorker(item: WorkItem): { actorId: string; occurredAt: strin }, undefined); } -export function workItemHumanActorIds(item: WorkItem): string[] { - const actorIds = [ - item.createdBy, - ...item.stageHistory.flatMap(entry => [entry.by, entry.exitedBy]), - ...Object.values(item.sessions).map(session => session.startedBy), - ].filter(isHumanActorId); - return [...new Set(actorIds)]; -} - export function workItemActivity(item: WorkItem, page: AuditEventPage | undefined): WorkItemActivity { const actors = page?.actors ?? {}; const auditEvents = page?.events.filter(event => targetsWorkItem(event, item.id)) ?? []; diff --git a/mastracode/factory-ui/src/ui/domains/search/components/FactoryGlobalSearchContent.tsx b/mastracode/factory-ui/src/ui/domains/search/components/FactoryGlobalSearchContent.tsx index 00fa27411eb..21e91fac41b 100644 --- a/mastracode/factory-ui/src/ui/domains/search/components/FactoryGlobalSearchContent.tsx +++ b/mastracode/factory-ui/src/ui/domains/search/components/FactoryGlobalSearchContent.tsx @@ -63,7 +63,7 @@ export function FactoryGlobalSearchContent({ factoryId, closeSearch }: { factory onFailure: toastFailureAfterPaletteCloses, items: workItems.loaded, }); - const runs = useBoardRuns({ factoryProjectId: factoryId, refetchItems: workItems.refetch }); + const runs = useBoardRuns({ factoryProjectId: factoryId }); const { effectByItem } = useItemDecisions(searchableFactoryId); const { selectPath } = useGlobalSearchNavigation(closeSearch); const [activeScope, setActiveScope] = useState('all'); diff --git a/mastracode/factory-ui/src/ui/domains/search/components/GlobalSearchNavigationResults.tsx b/mastracode/factory-ui/src/ui/domains/search/components/GlobalSearchNavigationResults.tsx index 0989138389c..5d6fd27f84e 100644 --- a/mastracode/factory-ui/src/ui/domains/search/components/GlobalSearchNavigationResults.tsx +++ b/mastracode/factory-ui/src/ui/domains/search/components/GlobalSearchNavigationResults.tsx @@ -3,7 +3,7 @@ import { CommandGroup } from '@mastra/playground-ui/components/Command'; import { CommandPaletteItem } from '@mastra/playground-ui/components/CommandPalette'; import { Brain, GitPullRequest, ListChecks, Settings, SquareKanban } from 'lucide-react'; -import { PULL_REQUEST_SOURCE_FILTER } from '../../factory/boardSourceFilters'; +import { PULL_REQUEST_SOURCE_FILTER } from '@mastra/factory/work-items/card-source-filters'; import { rememberedBoardPath } from '../../factory/services/boardViews'; import type { GlobalSearchSelectHandler } from '../services/searchNavigation'; import { SETTINGS_SECTION_LABELS, settingsSectionPath } from '../../settings/settingsSections'; diff --git a/mastracode/factory-ui/src/ui/domains/search/hooks/useGlobalSearchWorkItems.ts b/mastracode/factory-ui/src/ui/domains/search/hooks/useGlobalSearchWorkItems.ts index 1ddaec1c640..3882972747a 100644 --- a/mastracode/factory-ui/src/ui/domains/search/hooks/useGlobalSearchWorkItems.ts +++ b/mastracode/factory-ui/src/ui/domains/search/hooks/useGlobalSearchWorkItems.ts @@ -1,14 +1,12 @@ import { useDebouncedValue } from '@mastra/playground-ui/hooks/use-debounced-value'; import { keepPreviousData, skipToken, useQuery } from '@tanstack/react-query'; import { useMemo } from 'react'; -import { useLocation } from 'react-router'; import { useApiConfig } from '../../../../api/config'; import { queryKeys } from '../../../../api/keys'; -import { useSidebarWorkItemsQuery } from '../../../../hooks/useWorkItems'; +import { filedFromQueryOptions, useSidebarWorkItemsQuery } from '../../../../hooks/useWorkItems'; import type { BoardCandidate } from '../../factory/boardCandidates'; import { isPersistedCandidate, persistedSourceKeys } from '../../factory/boardItems'; -import { pageLoadsBoard } from '../../factory/pageLoadsBoard'; import { listWorkItems } from '../../factory/services/workItems'; import type { BoardSnapshot, WorkItem } from '../../factory/services/workItems'; import { candidateSearchValue } from '../services/searchResults'; @@ -63,11 +61,7 @@ function useUnstartedSearch(factoryId: string | undefined, search: string, candi const offered = bestCandidates(candidates, search); const sources = offered.flatMap(({ candidate }) => [candidate.sourceKey, candidate.url]).filter(Boolean); const filed = useQuery({ - queryKey: queryKeys.workItemsFiledFrom(factoryId, sources), - queryFn: - factoryId && sources.length > 0 - ? async ({ signal }) => ({ ...(await listWorkItems(baseUrl, factoryId, signal, { source: sources })), sources }) - : skipToken, + ...filedFromQueryOptions(baseUrl, factoryId, sources), placeholderData: keepPreviousData, }); const filedCards = filed.data?.workItems ?? NO_CARDS; @@ -94,9 +88,7 @@ function useUnstartedSearch(factoryId: string | undefined, search: string, candi * once typing pauses, and so are the cards already filed from the best unfiled candidates. */ export function useGlobalSearchWorkItems(factoryId: string | undefined, typed: string, candidates: Candidate[]) { - const { baseUrl } = useApiConfig(); - const { pathname } = useLocation(); - const sessionCards = useSidebarWorkItemsQuery(factoryId, pageLoadsBoard(pathname)); + const sessionCards = useSidebarWorkItemsQuery(factoryId); const withSessions = sessionCards.data?.workItems ?? NO_CARDS; const settled = useDebouncedValue(typed.trim(), 150); // Clearing the box goes back to the cached empty search at once. @@ -117,22 +109,6 @@ export function useGlobalSearchWorkItems(factoryId: string | undefined, typed: s /** Every card either search loaded, for acting on a row. A card several reads sent is in it several times. */ loaded, count: everything.count, - /** - * The clicked row's card alone, read fresh: it may have gained a session since it was listed, - * or been deleted. Not the lists again: a card can leave the search's first rows and still exist. - */ - refetch: async ( - itemId: string, - ): Promise<{ isSuccess: true; data: WorkItem[] } | { isSuccess: false; error: unknown }> => { - // Without a Factory no row is listed, so none is clicked. - if (!factoryId) return { isSuccess: true, data: NO_CARDS }; - try { - const card = await listWorkItems(baseUrl, factoryId, undefined, { workItemId: [itemId] }); - return { isSuccess: true, data: card.workItems }; - } catch (error) { - return { isSuccess: false, error }; - } - }, pending: sessionCards.isLoading || search.unstarted.isLoading, failed: sessionCards.isError || search.unstarted.isError || search.filed.isError, retry: () => { diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/components/__tests__/SessionsSectionSourceIcons.msw.test.tsx b/mastracode/factory-ui/src/ui/domains/workspaces/components/__tests__/SessionsSectionSourceIcons.msw.test.tsx index 079516cadd8..5508d5f3115 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/components/__tests__/SessionsSectionSourceIcons.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/domains/workspaces/components/__tests__/SessionsSectionSourceIcons.msw.test.tsx @@ -1,7 +1,6 @@ -import { screen, waitFor } from '@testing-library/react'; -import userEvent from '@testing-library/user-event'; +import { screen } from '@testing-library/react'; import { delay, http, HttpResponse } from 'msw'; -import { Link, MemoryRouter, Route, Routes } from 'react-router'; +import { MemoryRouter, Route, Routes } from 'react-router'; import { beforeEach, describe, expect, it } from 'vitest'; import { builtinBoardCatalog } from '../../../../../../e2e/ui/board-catalog'; @@ -130,44 +129,4 @@ describe('Sessions sidebar source icons', () => { expect(await iconFor('Add audit log')).toBe('linear-issue'); expect(await iconFor('Plan the migration')).toBe('user'); }); - - // The marks come from the board on a page that loads it, and elsewhere from the cards holding a - // session. Going from one to the other, the list the sidebar had keeps them. - it.each([ - { from: 'a page without the board', to: 'Work', start: '', next: '/work', unanswered: null }, - { from: 'Work', to: 'a page without the board', start: '/work', next: '', unanswered: 'sessions' }, - ])('keeps each mark while the next list loads, going from $from to $to', async ({ start, next, unanswered }) => { - let nextListAsked = false; - server.use( - http.get(`${TEST_BASE_URL}/web/factory/projects/${factoryId}/work-items`, async ({ request }) => { - if (new URL(request.url).searchParams.get('scope') !== unanswered) { - return HttpResponse.json({ workItems: cards }); - } - nextListAsked = true; - await delay('infinite'); - }), - ); - const user = userEvent.setup(); - renderWithProviders( - - - Next page - - } /> - - - , - ); - expect(await iconFor('Fix flaky login')).toBe('github-issue'); - expect(await iconFor('Review PR 12')).toBe('github-pr'); - - await user.click(screen.getByRole('link', { name: 'Next page' })); - - await waitFor(() => expect(nextListAsked).toBe(true)); - expect(screen.getByRole('link', { name: 'Fix flaky login' }).querySelector('[data-source]')).toHaveAttribute( - 'data-source', - 'github-issue', - ); - expect(screen.getByRole('link', { name: 'Review PR 12' })).toBeInTheDocument(); - }); }); diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useSessionListRows.ts b/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useSessionListRows.ts index 5acad385603..3527d7e8f5d 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useSessionListRows.ts +++ b/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useSessionListRows.ts @@ -9,7 +9,6 @@ import { allSessionRows, useWorkspacesQuery } from '../../../../hooks/useWorkspa import { AGENT_CONTROLLER_ID } from '../../chat/services/constants'; import { itemAwaitsPerson } from '../../factory/boardCardState'; import { useItemDecisions } from '../../factory/hooks/useBoardDecisions'; -import { pageLoadsBoard } from '../../factory/pageLoadsBoard'; import { buildFactorySessionRow, buildUserSessionRow, oneRowPerCard } from '../services/sessionRows'; import type { OneRowPerCardOptions, SessionListRow } from '../services/sessionRows'; import { sessionWorkItemIndex } from '../services/sessionWorkItems'; @@ -29,7 +28,7 @@ export function useSessionListRows( const { pathname } = useLocation(); const query = useWorkspacesQuery(factoryId); const factory = useFactoryQuery(factoryId); - const sessionCards = useSidebarWorkItemsQuery(factoryId, pageLoadsBoard(pathname)); + const sessionCards = useSidebarWorkItemsQuery(factoryId); const { proposalByItem, effectByItem } = useItemDecisions(factoryId); const catalog = useBoardCatalog(factoryId); const viewer = useFactoryAuth().data?.user; diff --git a/mastracode/factory-ui/src/ui/pages/__tests__/BoardPageFilters.msw.test.tsx b/mastracode/factory-ui/src/ui/pages/__tests__/BoardPageFilters.msw.test.tsx index f94a284c115..ca20c828af7 100644 --- a/mastracode/factory-ui/src/ui/pages/__tests__/BoardPageFilters.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/pages/__tests__/BoardPageFilters.msw.test.tsx @@ -14,7 +14,7 @@ import { togglePropertyOption, } from '../../../../e2e/ui/properties-menu'; import { renderWithProviders, TEST_BASE_URL, waitForMutationsIdle } from '../../../../e2e/ui/render'; -import { PULL_REQUEST_SOURCE_FILTER } from '../../domains/factory/boardSourceFilters'; +import { PULL_REQUEST_SOURCE_FILTER } from '@mastra/factory/work-items/card-source-filters'; import type { WorkItem } from '../../domains/factory/services/workItems'; import type { GithubIssue, GithubPullRequest } from '../../domains/factory/services/factory'; import { FactoryLayout } from '../../domains/workspaces/components/FactoryLayout'; diff --git a/mastracode/factory-ui/src/ui/pages/board/BoardContent.tsx b/mastracode/factory-ui/src/ui/pages/board/BoardContent.tsx index 74f36d8faa3..264f19aa53c 100644 --- a/mastracode/factory-ui/src/ui/pages/board/BoardContent.tsx +++ b/mastracode/factory-ui/src/ui/pages/board/BoardContent.tsx @@ -1,23 +1,37 @@ import { DEFAULT_BOARD_ID } from '@mastra/factory/boards/default-board'; +import type { ProviderPerson } from '@mastra/factory/work-items/card-people'; +import { searchWords } from '@mastra/factory/work-items/search-words'; import { boardLoop } from '../../domains/factory/boardFlow'; import { Notice } from '@mastra/playground-ui/components/Notice'; import { toast } from '@mastra/playground-ui/components/Toaster'; +import { useDebouncedValue } from '@mastra/playground-ui/hooks/use-debounced-value'; +import { useMemo, useState } from 'react'; import type { InstalledBoardInfo } from '../../../api/types'; import { useRecentAuditEvents } from '../../../hooks/useAuditEvents'; -import { cardMatchesSourceFilters, hasBoardSourceFilters } from '../../domains/factory/boardSourceFilters'; +import { hasBoardSourceFilters } from '../../domains/factory/boardSourceFilters'; import { useFactoryAuth } from '../../../hooks/useFactoryAuth'; import { useGithubStatusQuery } from '../../../hooks/useGithubStatus'; -import { stageContentCount } from '../../domains/factory/boardCandidates'; +import { + useBoardPhasesQuery, + useSidebarWorkItemsQuery, + useWorkItemFilterOptionsQuery, +} from '../../../hooks/useWorkItems'; +import { candidateMatchesView } from '../../domains/factory/boardCandidates'; import type { BoardCandidate } from '../../domains/factory/boardCandidates'; -import { boardLoadingStages, itemAppearsInStage } from '../../domains/factory/boardStages'; +import { shownBoardPhases } from '../../domains/factory/boardPhases'; +import type { ShownPhase } from '../../domains/factory/boardPhases'; +import { boardPhasesRequest, deeperPhaseWindow, isCardId } from '../../domains/factory/boardPhasesRequest'; +import { boardLoadingStages } from '../../domains/factory/boardStages'; import type { BoardKind } from '../../domains/factory/boardStages'; import { ConfigureBoardButton } from '../../domains/boardConfig/components/ConfigureBoardButton'; import { RepositoryPickerDialog } from '../../domains/factory/components/RepositoryPickerDialog'; +import { BoardItemsSkeleton } from '../../domains/factory/components/BoardItemsSkeleton'; import { BoardStageCards } from '../../domains/factory/components/BoardStageCards'; import { BoardEmptyStateActions } from '../../domains/factory/components/BoardEmptyStateActions'; import { BoardStageCreateButton } from '../../domains/factory/components/BoardStageCreateButton'; import { BoardViewControls } from '../../domains/factory/components/BoardViewControls'; +import { LoadMoreSentinel } from '../../domains/factory/components/LoadMoreSentinel'; import { useBoardComposer } from '../../domains/factory/hooks/useBoardComposer'; import { useBoardDeepLink } from '../../domains/factory/hooks/useBoardDeepLink'; import { useCollapsedStages } from '../../domains/factory/hooks/useCollapsedStages'; @@ -26,24 +40,18 @@ import { useBoardIntake } from '../../domains/factory/hooks/useBoardIntake'; import { useItemSessionStatuses } from '../../domains/factory/hooks/useItemSessionStatuses'; import { useBoardItems } from '../../domains/factory/hooks/useBoardItems'; import { useBoardRuns } from '../../domains/factory/hooks/useBoardRuns'; +import { useOpenCardState } from '../../domains/factory/hooks/useOpenCardState'; import { useRepositoryChoice } from '../../domains/factory/hooks/useRepositoryChoice'; -import { boardLabels, candidateMatchesLabels, workItemMatchesLabels } from '../../domains/factory/boardLabels'; -import { - boardParticipants, - boardPersonIdentity, - candidateMatchesPeople, - workItemMatchesPeople, -} from '../../domains/factory/boardPeople'; +import { boardLabels } from '../../domains/factory/boardLabels'; +import { boardParticipants, boardPersonIdentity, withPeopleUnfolded } from '../../domains/factory/boardPeople'; import { boardFiltersActive } from '../../domains/factory/boardFilters'; import { useBoardView } from '../../domains/factory/hooks/useBoardView'; import { BUSY_CARD_MOVE_REFUSAL, canMoveTo } from '../../domains/factory/boardCardState'; import { candidatePayload } from '../../domains/factory/boardDrag'; import type { DragPayload } from '../../domains/factory/boardDrag'; -import { cardMatchesSearch, isPersistedCandidate } from '../../domains/factory/boardItems'; -import { orderWorkItemsForStage } from '../../domains/factory/boardOrder'; +import { isPersistedCandidate } from '../../domains/factory/boardItems'; import type { WorkItem } from '../../domains/factory/services/workItems'; import { relatedWorkItemIndex } from '../../domains/factory/services/relationships'; -import { workItemHumanActorIds } from '../../domains/factory/workItemActivity'; import type { FactoryProject, LinkedRepositoryPayload } from '../../domains/workspaces/services/github'; import { VirtualBoardItems } from '../../domains/factory/components/VirtualBoardItems'; @@ -53,7 +61,14 @@ import { BoardStageCandidates } from '../../domains/factory/components/BoardStag import { BoardStages } from './BoardStages'; import { cardProjectRepositoryId } from '../../domains/factory/boardRepository'; -/** Count all available candidates before source filters so empty states can explain excluded cards. */ +const NO_CARDS: WorkItem[] = []; +const NO_WINDOWS: Readonly> = {}; +const NO_SESSIONS: readonly string[] = []; +const NO_ACTORS: string[] = []; +const NO_PEOPLE: readonly ProviderPerson[] = []; +const NO_LABELS: readonly string[] = []; +const NO_PHASE: ShownPhase = { cards: NO_CARDS, total: 0, listed: 0, listedAll: true }; + function countUnfilteredCandidates({ sourceFiltered, candidates, @@ -72,6 +87,12 @@ function countUnfilteredCandidates({ // One item can sit in several stages; each copy is its own card. const workItemCardKey = (stageId: string, itemId: string) => `${stageId}/${itemId}`; +/** The card a row's key names: a card id holds no `/`. The row of an issue not filed yet names none. */ +function keyedCardId(key: string | undefined): string | undefined { + const id = key?.slice(key.lastIndexOf('/') + 1); + return id !== undefined && isCardId(id) ? id : undefined; +} + export function BoardContent({ factory, repository, @@ -96,15 +117,35 @@ export function BoardContent({ const githubStatus = useGithubStatusQuery(); const personId = boardPersonIdentity(currentUserId, githubStatus.data?.userGithubUsername); const reviewsPullRequests = boardLoop(definition)?.pullRequestReview !== undefined; - const view = useBoardView({ factoryProjectId, kind, reviewsPullRequests, currentUserId, personId }); - const { searchParams, filters, sort, layout } = view; + const boardView = useBoardView({ factoryProjectId, kind, reviewsPullRequests, currentUserId, personId }); + const { searchParams, filters, sort, layout } = boardView; const targetItemId = searchParams.get('item') || undefined; + // The server is asked once typing pauses. Clearing the box goes back to the empty search at once. + const settledSearch = useDebouncedValue(boardView.search, 150); + const storedFilters = withPeopleUnfolded(filters, personId); + const view = boardPhasesRequest({ + board: kind, + sort, + search: boardView.search.trim() === '' ? '' : settledSearch, + filters: storedFilters, + windows: NO_WINDOWS, + item: targetItemId, + }); + // How deep each phase was scrolled is forgotten when the view changes: its phases start over. + const viewKey = JSON.stringify([view.sort, view.q, view.filters]); + const [deepened, setDeepened] = useState({ viewKey, windows: NO_WINDOWS }); + const windows = deepened.viewKey === viewKey ? deepened.windows : NO_WINDOWS; + const openCard = useOpenCardState(); + const phasesRead = useBoardPhasesQuery(factoryProjectId, { ...view, windows }, keyedCardId(openCard.openKey)); + const snapshot = phasesRead.data; + const cards = snapshot?.workItems ?? NO_CARDS; + const sessionCards = useSidebarWorkItemsQuery(factoryProjectId).data?.workItems ?? NO_CARDS; - const items = useBoardItems({ factoryProjectId, kind, currentUserId }); + const items = useBoardItems({ factoryProjectId, kind, currentUserId, items: [...cards, ...sessionCards] }); const repositoryChoice = useRepositoryChoice(factory, definition); const cardForDrop = (payload: DragPayload) => { if (payload.kind === 'candidate') return payload.candidate; - return items.all.find(item => item.id === payload.id); + return cards.find(item => item.id === payload.id); }; const dropWithRepository = ( payload: DragPayload, @@ -144,61 +185,56 @@ export function BoardContent({ factoryProjectId, repositories: factory.repositories, definition, - knownSourceKeys: items.knownSourceKeys, - elsewhereSourceKeys: items.elsewhereSourceKeys, sourceFilters: filters, }); const sourceFiltered = hasBoardSourceFilters(filters); - const runs = useBoardRuns({ factoryProjectId, refetchItems: () => items.refetch() }); - const relatedItemsFor = relatedWorkItemIndex(items.all); + const runs = useBoardRuns({ factoryProjectId }); + const relatedItemsFor = useMemo(() => relatedWorkItemIndex(cards), [cards]); const sessionStatuses = useItemSessionStatuses({ factoryProjectId, projectRepositoryId: repository.projectRepositoryId, - items: items.all, + items: cards, + parkedSessionIds: snapshot?.parkedSessionIds ?? NO_SESSIONS, }); const decisions = useBoardDecisions(factoryProjectId); const composer = useBoardComposer(factoryProjectId, definition, currentUserId); - const activityProfileActorIds = [...new Set(items.all.flatMap(workItemHumanActorIds))]; - const activity = useRecentAuditEvents(factoryProjectId, `board-${kind}-activity`, 200, activityProfileActorIds); + const filterOptions = useWorkItemFilterOptionsQuery(factoryProjectId).data; + const activity = useRecentAuditEvents( + factoryProjectId, + `board-${kind}-activity`, + 200, + filterOptions?.actorIds ?? NO_ACTORS, + ); const activityPage = activity.data; const participants = boardParticipants({ - items: items.all, + people: filterOptions?.people ?? NO_PEOPLE, candidates: intake.participantCandidates, activityPage, currentUser: auth.data?.user, personId, }); - const participantCandidateBySourceKey = new Map( - intake.participantCandidates.map(candidate => [candidate.sourceKey, candidate]), + const availableLabels = boardLabels({ + labels: filterOptions?.labels ?? NO_LABELS, + candidates: intake.participantCandidates, + }); + // The server searches and filters the cards; issues not filed yet are matched here, by its rules. + const searchedWords = searchWords(view.q); + const filteredCandidates = intake.candidates.filter(candidate => + candidateMatchesView(candidate, storedFilters, searchedWords), ); - const availableLabels = boardLabels({ items: items.all, candidates: intake.participantCandidates }); - const candidateMatchesView = (candidate: BoardCandidate): boolean => { - if (!candidateMatchesPeople(candidate, filters, personId)) return false; - if (!candidateMatchesLabels(candidate, filters.label)) return false; - if (!cardMatchesSourceFilters(candidate, filters)) return false; - return cardMatchesSearch(candidate, view.search); - }; - const filteredCandidates = intake.candidates.filter(candidateMatchesView); - const unfilteredWorkItemsForStage = (stage: (typeof stages)[number]['id']) => - items.visible.filter(item => itemAppearsInStage(item, stage, stages)); - const workItemMatchesView = (item: WorkItem): boolean => { - const liveCandidate = item.sourceKey ? participantCandidateBySourceKey.get(item.sourceKey) : undefined; - if (!workItemMatchesPeople(item, activityPage, filters, personId, liveCandidate)) return false; - if (!workItemMatchesLabels(item, filters.label, liveCandidate)) return false; - if (!cardMatchesSourceFilters(item, filters, liveCandidate)) return false; - return cardMatchesSearch(item, view.search); - }; - const workItemsForStage = (stage: (typeof stages)[number]['id']) => { - const matchingItems = unfilteredWorkItemsForStage(stage).filter(workItemMatchesView); - return orderWorkItemsForStage(matchingItems, stage, sort, currentUserId); - }; - const workItemsByStage = new Map(stages.map(stage => [stage.id, workItemsForStage(stage.id)])); - const boardWorkItems = [...workItemsByStage.values()].flat(); - const targetReady = !items.isPending && (!targetItemId || boardWorkItems.some(item => item.id === targetItemId)); + const shownPhases = useMemo(() => shownBoardPhases(snapshot, definition.phases), [snapshot, definition.phases]); + const targetStages = targetItemId + ? stages + .filter(stage => shownPhases.get(stage.id)?.cards.some(item => item.id === targetItemId)) + .map(stage => stage.id) + : []; + const targetListed = targetStages.length > 0; + const viewAnswered = phasesRead.data !== undefined && !phasesRead.isPlaceholderData; + const targetReady = !phasesRead.isPending && (!targetItemId || targetListed); const loadingStages = boardLoadingStages({ board: definition, stages, - itemsPending: items.isPending, + itemsPending: phasesRead.isPending, intakePending: intake.isPending, triagePending: intake.isTriagePending, }); @@ -207,51 +243,51 @@ export function BoardContent({ targetItemId, targetReady, }); - const targetStages = stages - .filter(stage => workItemsByStage.get(stage.id)?.some(item => item.id === targetItemId)) - .map(stage => stage.id); const collapsedStages = useCollapsedStages( - targetItemId && targetStages.length > 0 ? { itemId: targetItemId, stages: targetStages } : undefined, + targetItemId && targetListed ? { itemId: targetItemId, stages: targetStages } : undefined, ); - if (items.error !== undefined) { + if (phasesRead.isError) { return (
- - {items.error instanceof Error ? items.error.message : 'Failed to load the board'} + void phasesRead.refetch()}>Retry} + > + {phasesRead.error instanceof Error ? phasesRead.error.message : 'Failed to load the board'}
); } const mutationError = runs.error ?? decisions.error ?? items.mutationError; - const visibleWorkItems = new Set(boardWorkItems); - const unfilteredVisibleWorkItems = new Set(stages.flatMap(stage => unfilteredWorkItemsForStage(stage.id))); - const totalTaskCount = visibleWorkItems.size + filteredCandidates.length; + const totalTaskCount = (snapshot?.matchingTotal ?? 0) + filteredCandidates.length; const unfilteredCandidateCount = countUnfilteredCandidates({ sourceFiltered, candidates: intake.candidates, participantCandidates: intake.participantCandidates, - knownSourceKeys: items.knownSourceKeys, + knownSourceKeys: intake.knownSourceKeys, }); - const unfilteredTaskCount = unfilteredVisibleWorkItems.size + unfilteredCandidateCount; - const anyFilterActive = boardFiltersActive(filters) || view.search.trim() !== ''; - const filtersExcludeAll = anyFilterActive && totalTaskCount === 0 && unfilteredTaskCount > 0; + const unfilteredTaskCount = (snapshot?.boardTotal ?? 0) + unfilteredCandidateCount; + const anyFilterActive = boardFiltersActive(filters) || view.q !== ''; + // The phases of the view before a change stay up until the new ones answer: they say nothing of it. + const filtersExcludeAll = viewAnswered && anyFilterActive && totalTaskCount === 0 && unfilteredTaskCount > 0; const intakeSetup = intake.fed ? undefined : intake.unrouted ? 'route' : 'source'; const stageViews = stages.map(stage => { const isInitialPhase = stage.id === definition.initialPhase; const loading = loadingStages.has(stage.id); - const stageWorkItems = workItemsByStage.get(stage.id) ?? []; + const shown = shownPhases.get(stage.id) ?? NO_PHASE; const stageCandidates = filteredCandidates.filter(candidate => candidate.column === stage.id); - const taskCount = stageContentCount(stage.id, stages, stageWorkItems, filteredCandidates); + const taskCount = shown.total + stageCandidates.length; const composerOpen = composer.stage === stage.id; const columnFeed = intake.feedByColumn[stage.id]; const feedFailed = Boolean(columnFeed?.error); // No card is created by hand on the retired Review board: its cards come from pull requests. const canCreate = !pullRequestsOnly && - !items.isPending && + !phasesRead.isPending && stage.kind !== 'terminal' && (composer.stage === undefined || composerOpen); const stageIntakeSetup = isInitialPhase ? intakeSetup : undefined; @@ -291,7 +327,8 @@ export function BoardContent({ layout={layout} loading={loading} taskCount={taskCount} - feed={columnFeed} + // The feed's notices and paging follow the candidates, after the column's last card. + feed={shown.listedAll ? columnFeed : undefined} intakeSource={intake.active} intakeSetup={intakeSetup} filtersExcludeAll={filtersExcludeAll} @@ -302,7 +339,7 @@ export function BoardContent({ factoryId={factoryProjectId} intakeSetup={stageIntakeSetup} onCreate={canCreate ? () => composer.open(stage.id) : undefined} - onClearFilters={filtersExcludeAll ? view.clearFilters : undefined} + onClearFilters={filtersExcludeAll ? boardView.clearFilters : undefined} /> ) } @@ -318,7 +355,7 @@ export function BoardContent({ } > workItemCardKey(stage.id, item.id)} layout={layout} pinnedKey={targetItemId && workItemCardKey(stage.id, targetItemId)} @@ -361,19 +398,41 @@ export function BoardContent({ /> )} /> - 0} - layout={layout} - projectRepositoryId={candidate => - cardProjectRepositoryId(factory.repositories, candidate, repository.projectRepositoryId) + shown.listed) } - factoryProjectId={factoryProjectId} - board={definition} - onRun={(candidate, move, prompt) => - dropWithRepository(candidatePayload(candidate, prompt), move.stage, 'card_action') + onLoadMore={() => + // From the windows as they stand: two ends coming into view together both list deeper. + setDeepened(current => ({ + viewKey, + windows: { + ...(current.viewKey === viewKey ? current.windows : NO_WINDOWS), + [stage.id]: deeperPhaseWindow(shown.listed), + }, + })) } + label="Load more cards" + loadingIndicator={} /> + {shown.listedAll && ( + 0} + layout={layout} + projectRepositoryId={candidate => + cardProjectRepositoryId(factory.repositories, candidate, repository.projectRepositoryId) + } + factoryProjectId={factoryProjectId} + board={definition} + onRun={(candidate, move, prompt) => + dropWithRepository(candidatePayload(candidate, prompt), move.stage, 'card_action') + } + /> + )} ), }; @@ -406,11 +465,12 @@ export function BoardContent({ layout={layout} stages={stageViews} totalTaskCount={totalTaskCount} + openCard={openCard} onDrop={dropWithRepository} toolbar={ void; toolbar: ReactNode; }) { const scrollRef = useRef(null); - const openCard = useOpenCardState(); return ( diff --git a/mastracode/factory-ui/src/ui/routeLoaders.ts b/mastracode/factory-ui/src/ui/routeLoaders.ts index d79cd7e357c..3bc8fef1a75 100644 --- a/mastracode/factory-ui/src/ui/routeLoaders.ts +++ b/mastracode/factory-ui/src/ui/routeLoaders.ts @@ -1,3 +1,5 @@ +import { DEFAULT_BOARD_ID } from '@mastra/factory/boards/default-board'; +import { PULL_REQUEST_SOURCE_FILTER } from '@mastra/factory/work-items/card-source-filters'; import { noop } from '@tanstack/react-query'; import type { QueryClient } from '@tanstack/react-query'; import type { LoaderFunctionArgs } from 'react-router'; @@ -18,11 +20,21 @@ import { intakeBindingsQueryOptions, intakeConfigQueryOptions } from '../hooks/u import { jiraStatusQueryOptions } from '../hooks/useJiraData'; import { linearStatusQueryOptions } from '../hooks/useLinearData'; import { serverFeaturesQueryOptions } from '../hooks/useServerFeatures'; -import { boardQueryOptions, workItemActivityQueryOptions, workItemStartersQueryOptions } from '../hooks/useWorkItems'; +import { + boardPhasesQueryOptions, + sessionCardsQueryOptions, + workItemActivityQueryOptions, + workItemFilterOptionsQueryOptions, + workItemStartersQueryOptions, +} from '../hooks/useWorkItems'; import { workspacesQueryOptions } from '../hooks/useWorkspaces'; import { AGENT_CONTROLLER_ID } from './domains/chat/services/constants'; +import { boardPhasesRequest } from './domains/factory/boardPhasesRequest'; +import { boardFiltersFromParams } from './domains/factory/boardFilters'; +import { BOARD_VIEW_QUERY } from './domains/factory/boardSavedViews'; +import { BOARD_SORT_QUERY, DEFAULT_BOARD_SORT, isBoardSort } from './domains/factory/boardSort'; import { boardDecisionsQueryOptions } from './domains/factory/hooks/useBoardDecisions'; -import { pageLoadsBoard } from './domains/factory/pageLoadsBoard'; +import { BOARD_SEARCH_QUERY } from './domains/factory/hooks/useBoardView'; import { DEFAULT_ACTIVITY_PERIOD } from './domains/factory/periodActivity'; import { ruleDecisionGroup } from './domains/factory/ruleDecisionGroups'; import { isSettingsPath } from './domains/settings/hooks/useSettingsOpen'; @@ -88,21 +100,32 @@ export const prefetchSidebar: Prefetch = (services, { params, request }) => { void queryClient.query(boardCatalogQueryOptions(api.client, factoryId)).catch(noop); // Says whether the sidebar offers "New board": only organization admins may change boards. void queryClient.query(intakeRoutesQueryOptions(api.baseUrl, factoryId)).catch(noop); - // A page that loads the board shares it with the sidebar. - if (!pageLoadsBoard(pathname)) { - void queryClient.query(boardQueryOptions(api.baseUrl, factoryId, 'sessions')).catch(noop); - } + void queryClient.query(sessionCardsQueryOptions(api.baseUrl, factoryId)).catch(noop); void queryClient.query(boardDecisionsQueryOptions(api.baseUrl, factoryId)).catch(noop); prefetchSessionRuns(services, factoryId); }; -export const prefetchBoard: Prefetch = (services, { params }) => { +export const prefetchBoard: Prefetch = (services, { params, request }) => { const { factoryId } = params; if (!factoryId) return; const { queryClient, api } = services; // The page's largest read leaves with the Factory list, not once it answers: waiting to hear a - // repository is linked would start every board a round trip later. - void queryClient.query(boardQueryOptions(api.baseUrl, factoryId)).catch(noop); + // repository is linked would start every board a round trip later. A saved view keeps its + // filters in the browser's storage, so the page asks for that one itself. + const { searchParams } = new URL(request.url); + if (!searchParams.has(BOARD_VIEW_QUERY)) { + const sort = searchParams.get(BOARD_SORT_QUERY); + const view = boardPhasesRequest({ + board: params.boardId ?? DEFAULT_BOARD_ID, + sort: sort && isBoardSort(sort) ? sort : DEFAULT_BOARD_SORT, + search: searchParams.get(BOARD_SEARCH_QUERY) ?? '', + filters: boardFiltersFromParams(searchParams, true), + windows: {}, + item: searchParams.get('item') ?? undefined, + }); + void queryClient.query(boardPhasesQueryOptions(api.baseUrl, factoryId, view)).catch(noop); + } + void queryClient.query(workItemFilterOptionsQueryOptions(api.baseUrl, factoryId)).catch(noop); whenFactoryListed(services, factoryId, factory => { if (!hasLinkedRepository(factory)) return; void queryClient.query(intakeConfigQueryOptions(api.baseUrl)).catch(noop); @@ -115,6 +138,21 @@ export const prefetchBoard: Prefetch = (services, { params }) => { }); }; +/** Where a link to the retired Review board lands on Work: the link's query, with pull requests alone. */ +export function retiredReviewBoardSearch(search: string): URLSearchParams { + const params = new URLSearchParams(search); + // Picked sources widen the filter, so any other source would show cards the Review board never held. + params.set('source', PULL_REQUEST_SOURCE_FILTER); + return params; +} + +/** A retired Review board link opens Work once the catalog says the board is gone: what Work reads starts now. */ +export const prefetchRetiredReviewBoard: Prefetch = (services, args) => { + const url = new URL(args.request.url); + url.search = retiredReviewBoardSearch(url.search).toString(); + prefetchBoard(services, { ...args, request: new Request(url, { signal: args.request.signal }) }); +}; + export const prefetchComposer: Prefetch = ({ queryClient, api }, { params }) => { const { factoryId } = params; if (!factoryId) return; diff --git a/mastracode/factory-ui/src/ui/router.tsx b/mastracode/factory-ui/src/ui/router.tsx index cb307ee4b5f..78e5bb67ac1 100644 --- a/mastracode/factory-ui/src/ui/router.tsx +++ b/mastracode/factory-ui/src/ui/router.tsx @@ -17,7 +17,6 @@ import type { RouteObject } from 'react-router'; import { FactoryBoardLanding } from './domains/factory/components/FactoryBoardLanding'; import { boardConfigPath, boardSkillsPath, newBoardPath } from './domains/boardConfig/boardConfigPaths'; import { AuthPendingSkeleton, RootGuards } from './domains/auth/components/RootGuards'; -import { PULL_REQUEST_SOURCE_FILTER } from './domains/factory/boardSourceFilters'; import { CustomBoardPage, WorkBoardPage } from './pages/BoardPage'; import { useBoardCatalog } from '../hooks/useBoardCatalog'; @@ -37,7 +36,9 @@ import { prefetchFactories, prefetchFactoryLayout, prefetchRuleDecisions, + prefetchRetiredReviewBoard, prefetchSidebar, + retiredReviewBoardSearch, } from './routeLoaders'; import type { Prefetch, RouteLoaderServices } from './routeLoaders'; import { pendingCreateFlowFactoryId } from './domains/workspaces/hooks/useCreateFactoryFlow'; @@ -135,10 +136,7 @@ function RetiredReviewBoardRedirect() { if (catalog.isPending) return null; if (catalog.data?.some(board => board.id === 'review')) return ; - const params = new URLSearchParams(search); - // Picked sources widen the filter, so any other source would show cards the Review board never held. - params.set('source', PULL_REQUEST_SOURCE_FILTER); - return ; + return ; } function FactoryHomeRedirect() { @@ -266,7 +264,11 @@ export function createAppRoutes(services?: RouteLoaderServices): RouteObject[] { { path: 'new-board', ...lazyRoute(NewBoardPage) }, { path: 'work', element: , ...loadOnEntry(prefetchBoard) }, // The Review board was retired: new pull requests live on Work. - { path: 'review', element: , ...loadOnEntry(prefetchBoard) }, + { + path: 'review', + element: , + ...loadOnEntry(prefetchRetiredReviewBoard), + }, { path: 'boards/:boardId', element: , ...loadOnEntry(prefetchBoard) }, { path: 'work/config/:phaseKey?', ...lazyRoute(BoardConfigPage) }, { path: 'boards/:boardId/config/:phaseKey?', ...lazyRoute(BoardConfigPage) }, From 9c8d3377e4025215380808ad7595288c0276bdda Mon Sep 17 00:00:00 2001 From: Daniel Lew <51924260+DanielSLew@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:37:03 -0800 Subject: [PATCH 005/239] docs: built-in MCP server tools reference, client setup, and access control (#30232) Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> Co-authored-by: mastra-platform[bot] --- .../docs/guides/authentication-identity.mdx | 14 +- docs/src/content/en/docs/server/mcp.mdx | 34 ++++- docs/src/content/en/docs/server/overview.mdx | 1 + .../en/docs/server/server-adapters.mdx | 2 + docs/src/content/en/docs/studio/auth.mdx | 6 +- docs/src/content/en/docs/studio/editor.mdx | 17 +++ docs/src/content/en/docs/studio/overview.mdx | 2 +- docs/src/content/en/reference/auth/auth0.mdx | 2 + docs/src/content/en/reference/auth/clerk.mdx | 4 + docs/src/content/en/reference/auth/jwt.mdx | 4 + .../en/reference/server/builtin-mcp-tools.mdx | 139 ++++++++++++++++++ docs/src/content/en/reference/sidebars.js | 1 + .../content/en/reference/tools/mcp-server.mdx | 2 + 13 files changed, 224 insertions(+), 4 deletions(-) create mode 100644 docs/src/content/en/reference/server/builtin-mcp-tools.mdx diff --git a/docs/src/content/en/docs/guides/authentication-identity.mdx b/docs/src/content/en/docs/guides/authentication-identity.mdx index 5e1b377f770..f3815554cbb 100644 --- a/docs/src/content/en/docs/guides/authentication-identity.mdx +++ b/docs/src/content/en/docs/guides/authentication-identity.mdx @@ -107,7 +107,19 @@ Choose the narrowest boundary that matches how people should share state: | Shared memory for an organization | `user.organizationId` | | User memory within a workspace and project | `${workspaceId}:${projectId}:${userId}` | -Mastra applies this boundary automatically to memory and thread operations. Application code can continue using the authenticated user in `RequestContext` when it authorizes database records or external services. +Mastra applies this boundary automatically to memory and thread operations, including Observational Memory. `GET /api/memory/observational-memory`, `POST /api/memory/observational-memory/buffer-status`, and the Observational Memory details in `GET /api/memory/status` return `403` when the requested thread belongs to another resource or an [FGA](/docs/auth/fga) check denies it. Without `server.auth`, these routes use the `resourceId` and `threadId` the client sends, but a thread paired with a different `resourceId` still gets `403`. Application code can continue using the authenticated user in `RequestContext` when it authorizes database records or external services. + +### User IDs from JWT providers + +[`MastraJwtAuth`](/reference/auth/jwt), [Auth0](/reference/auth/auth0), and [Clerk](/reference/auth/clerk) set the authenticated user's `id` to the token's `sub` claim when the token has no `id` claim. A token with its own `id` claim keeps it. RBAC loads roles by `id`, and `id` is also the owner of the records a user creates when `mapUserToResourceId` isn't set. + +Without `mapUserToResourceId`, this means: + +- Each user sees their own stored agents, skills, workspaces, and other owned records plus public ones. Records they create are owned by them and private by default. Records created before your app used these user IDs have no owner and stay visible to everyone. Users with an admin permission such as `stored-agents:admin` still see every record. +- Per-author tool-provider connections are stored under the user's `id`. Connections saved under the shared `default` owner aren't found, so users reconnect them. Shared connections aren't affected. +- Feedback is recorded with the user's `id` as the user ID. + +To keep every user in one shared resource instead, pass `mapUserToResourceId: () => 'default'` to the auth provider. This also shares memory and owned records between all users, so use it only when that's how your app should work. ## Enforce identity at the data boundary diff --git a/docs/src/content/en/docs/server/mcp.mdx b/docs/src/content/en/docs/server/mcp.mdx index 68a9656ec8f..3d1a1426e84 100644 --- a/docs/src/content/en/docs/server/mcp.mdx +++ b/docs/src/content/en/docs/server/mcp.mdx @@ -58,6 +58,35 @@ npx @modelcontextprotocol/inspector --cli http://localhost:4111/api/mcp \ --transport http --header "Authorization: Bearer $MASTRA_TOKEN" --method tools/list ``` +Cursor and VS Code read the server from a JSON file. Add it to `.cursor/mcp.json` for Cursor: + +```json title=".cursor/mcp.json" +{ + "mcpServers": { + "mastra": { + "url": "http://localhost:4111/api/mcp", + "headers": { "Authorization": "Bearer " } + } + } +} +``` + +Or to `.vscode/mcp.json` for VS Code: + +```json title=".vscode/mcp.json" +{ + "servers": { + "mastra": { + "type": "http", + "url": "http://localhost:4111/api/mcp", + "headers": { "Authorization": "Bearer " } + } + } +} +``` + +Leave out `headers` when the server runs without `server.auth`. Clients that take only a URL and can't send an `Authorization` header, such as custom connectors in the Claude apps, need [OAuth discovery](#oauth-discovery) and an identity provider that lets them sign in. + The endpoint uses stateless Streamable HTTP and speaks both MCP `2026-07-28` and the 2025 revisions that current clients use, so no session is kept between requests. ### In Studio @@ -72,6 +101,8 @@ Studio reads this from `GET /api/mcp/builtin`, which needs the `mcp:read` permis The server groups tools into toolsets. This section covers `agents`, `workflows`, and `tools`; see [Memory, observability, and agent builder](#memory-observability-and-agent-builder) for the others. Agents and workflows are reached through operation tools that take the id as an argument. The tool list stays the same size however many agents you add. +See the [built-in MCP tools reference](/reference/server/builtin-mcp-tools) for every tool's arguments, route, and permission. + | Toolset | Tools | Backing HTTP route | | - | - | - | | `agents` | `list_agents`, `get_agent`, `call_agent` | `GET /agents`, `GET /agents/:agentId`, `POST /agents/:agentId/generate` | @@ -179,7 +210,7 @@ export const mastra = new Mastra({ ### Agents creating agents -`create_stored_agent` lets an MCP client create agents that other clients can then call. It needs `stored-agents:write`. A created agent's `visibility` (private by default) controls who can read and edit its stored configuration through the `stored_agents` tools. It doesn't limit who can call the agent: any user who can call agents can call it with `call_agent`, the same as over HTTP. When the agent builder restricts models, the MCP tools accept only allowed models for the agent's model (the `provider` and `name` it runs, in each conditional variant), for any model named in `defaultOptions` (such as `structuredOutput.model`), for each enabled entry of the fallback `modelList`, for the memory models (the Observational Memory observer and reflector models and the title model), and for the `model` of every input and output processor step, at any depth of the processor graph. They also reject anything that would run on a default model the policy can't check: `observationalMemory: true`, an Observational Memory config without a `model`, memory left out on create (which the agent builder fills with Observational Memory on its default model), or a processor that needs a model, such as `moderation`, without one. Set an allowed `model` instead. A stored `model` takes only `provider`, `name`, and model settings such as `temperature`. Other keys, such as `modelId` or `providerId`, are rejected. If the agent builder's policy can't be loaded, the tools return an error instead of saving unchecked. `list_available_models` returns the allowed models. The HTTP route doesn't apply this check, so a user who can call `POST /stored/agents` directly can still save any model. Embedding models (`memory.embedder`) aren't on the builder's model list and aren't checked. Tool allowlists aren't checked when an agent is saved, so a created agent can use any tool the server has. Its tools run with the permissions of the user who calls it. +`create_stored_agent` lets an MCP client create agents that other clients can then call. It needs `stored-agents:write`. A created agent is owned by the caller and is private by default. Without a caller identity, such as when `server.auth` isn't configured, the agent has no owner and is public, even with `visibility: 'private'`. Other users don't see a private agent in `list_agents` or `list_stored_agents`, and unless they're admins or granted that agent by id, calling it answers as if it doesn't exist, the same as over HTTP. Set `visibility: 'public'` to let every user call it. Only the owner, admins, and users granted that agent by id can edit it either way. An agent with no owner can be edited by any user with `stored-agents:write`. See [stored agent visibility](/docs/studio/editor#visibility). When the agent builder restricts models, the MCP tools accept only allowed models for the agent's model (the `provider` and `name` it runs, in each conditional variant), for any model named in `defaultOptions` (such as `structuredOutput.model`), for each enabled entry of the fallback `modelList`, for the memory models (the Observational Memory observer and reflector models and the title model), and for the `model` of every input and output processor step, at any depth of the processor graph. They also reject anything that would run on a default model the policy can't check: `observationalMemory: true`, an Observational Memory config without a `model`, memory left out on create (which the agent builder fills with Observational Memory on its default model), or a processor that needs a model, such as `moderation`, without one. Set an allowed `model` instead. A stored `model` takes only `provider`, `name`, and model settings such as `temperature`. Other keys, such as `modelId` or `providerId`, are rejected. If the agent builder's policy can't be loaded, the tools return an error instead of saving unchecked. `list_available_models` returns the allowed models. The HTTP route doesn't apply this check, so a user who can call `POST /stored/agents` directly can still save any model. Embedding models (`memory.embedder`) aren't on the builder's model list and aren't checked. Tool allowlists aren't checked when an agent is saved, so a created agent can use any tool the server has. Its tools run with the permissions of the user who calls it. Observational Memory starts observing only after a thread reaches its token threshold, 30,000 tokens by default. For a short demo, set a lower `observation.messageTokens` so the agent learns from a few messages. Observational Memory processes messages in the background, so right after `call_agent`, call `get_observations` with `waitForPending: true` to wait (up to 30 seconds) for it to finish before reading. @@ -298,6 +329,7 @@ The endpoint doesn't return `403` with `error="insufficient_scope"` yet. A calle ## Related +- [Built-in MCP tools reference](/reference/server/builtin-mcp-tools) - [`server.mcp` configuration reference](/reference/configuration#servermcp) - [MCP connections](/docs/connections/mcp) - [Authentication overview](/docs/auth/overview) diff --git a/docs/src/content/en/docs/server/overview.mdx b/docs/src/content/en/docs/server/overview.mdx index d3f0d67be39..fda987a0056 100644 --- a/docs/src/content/en/docs/server/overview.mdx +++ b/docs/src/content/en/docs/server/overview.mdx @@ -23,6 +23,7 @@ This page covers the [`server`](/reference/configuration#server-options) configu - **[Server Adapters](/docs/server/server-adapters)**: Run Mastra with Express, Hono, or your own HTTP server instead of the generated server. - **[Custom Adapters](/docs/server/custom-adapters)**: Build adapters for frameworks not officially supported. - **[Mastra Client SDK](/docs/server/mastra-client)**: Type-safe client for calling agents, workflows, and tools from browser or server environments. +- **[Built-in MCP server](/docs/server/mcp)**: Let MCP clients such as Claude Code and Cursor call your agents, workflows, and tools at `/api/mcp`, with the same auth and permissions as the HTTP API. - **[A2A](/docs/connections/a2a)**: Expose agents through A2A agent cards and task streams, plus push notifications. - **[Authentication](/docs/auth/overview)**: Secure endpoints with JWT, Clerk, Supabase, Firebase, Auth0, or WorkOS. diff --git a/docs/src/content/en/docs/server/server-adapters.mdx b/docs/src/content/en/docs/server/server-adapters.mdx index 436b0e83738..75bf9ab0802 100644 --- a/docs/src/content/en/docs/server/server-adapters.mdx +++ b/docs/src/content/en/docs/server/server-adapters.mdx @@ -372,6 +372,8 @@ const server = new MastraServer({ With this prefix, Mastra routes become `/api/v2/agents`, `/api/v2/workflows`, etc. Custom routes you add directly to the app aren't affected by this prefix. +The [built-in MCP server](/docs/server/mcp) moves with the prefix to `/api/v2/mcp`. Its OAuth metadata stays at the server root, at `/.well-known/oauth-protected-resource/api/v2/mcp`. + ## OpenAPI spec Mastra can generate an OpenAPI specification for all registered routes. This is useful for documentation or client generation, including integration with API tools. Enable it by setting the `openapiPath` option: diff --git a/docs/src/content/en/docs/studio/auth.mdx b/docs/src/content/en/docs/studio/auth.mdx index b30c2ba03d2..546c1c0b721 100644 --- a/docs/src/content/en/docs/studio/auth.mdx +++ b/docs/src/content/en/docs/studio/auth.mdx @@ -135,7 +135,11 @@ Permissions follow the pattern `{resource}:{action}`, with optional resource-lev | `agents:execute` | Execute agents only | | `agents:read:my-id` | Read a specific agent by ID | -Resources include `agents`, `workflows`, `tools`, `datasets`, `memory`, `scores`, `observability`, and others. Actions are `read`, `write`, `create`, `delete`, `execute`, `publish`, and `share`. +Resources include `agents`, `workflows`, `tools`, `datasets`, `memory`, `scores`, `observability`, `stored-agents`, `mcp`, and others. Actions are `read`, `write`, `create`, `delete`, `execute`, `publish`, and `share`. + +`mcp:read` and `mcp:execute` gate the [built-in MCP server](/docs/server/mcp#authentication-and-permissions) and the routes of `MCPServer` instances you register. The default `viewer` role has `mcp:read` only, so a viewer can connect but gets an empty tool list. Each MCP tool call also needs the permission of the route it runs, such as `agents:execute`. + +Stored agents are private to their owner by default. `stored-agents:*` lets a user see and edit every stored agent. `stored-agents:admin` lifts the owner check, but the user still needs each route's own permission, such as `stored-agents:read` or `stored-agents:write`. The default `admin` role doesn't include either. See [stored agent visibility](/docs/studio/editor#visibility). ### Map external provider roles diff --git a/docs/src/content/en/docs/studio/editor.mdx b/docs/src/content/en/docs/studio/editor.mdx index 2393c8607af..7973fa2d999 100644 --- a/docs/src/content/en/docs/studio/editor.mdx +++ b/docs/src/content/en/docs/studio/editor.mdx @@ -321,6 +321,23 @@ The same version controls work when a supervisor calls sub-agents. Developers ca See the [Editor versioning reference](/reference/editor/versioning) for version selection, sub-agent behavior, REST endpoints, and SDK methods. +## Visibility + +With [`server.auth`](/docs/auth/overview) configured, every stored agent has an owner and a `visibility`. An agent created in Studio, through `POST /api/stored/agents`, or with the [built-in MCP server](/docs/server/mcp) is owned by the user who created it and is `private` unless they set `visibility: 'public'`. The owner is the caller's resource ID from `mapUserToResourceId`, or the user's `id` without it. Without `server.auth`, or when the caller has neither, stored agents have no owner, are `public`, and every caller can use them. + +| Who | Can see and call a private agent | Can edit or delete it | +| - | - | - | +| Owner | Yes | Yes | +| Users with `*`, `stored-agents:*`, or `stored-agents:admin` | Yes | Yes | +| Users granted that agent by id, for example `stored-agents:read:support-agent` or `stored-agents:edit:support-agent` | Yes, with a `read` grant. An `execute` grant only lets them call it | Yes, with an `edit` or `delete` grant | +| Everyone else | No | No | + +The table covers ownership only. Each route still checks its own permission, such as `stored-agents:write` to edit or `agents:execute` to call, so an admin or id grant works only alongside the route permission. A grant by id only works when the agent is requested by its id. The agent still doesn't appear in their `GET /api/agents` or `GET /api/stored/agents` list. + +A `public` agent can be seen and called by every user, but only the users in the table can edit or delete it. Agents saved before they had an owner stay visible to everyone, and any user with the route permission can edit or delete them. Code-defined agents aren't affected, including ones with Editor overrides. + +The rules apply to every route that looks up an agent, not only `/api/stored/agents`. To another user, a private agent behaves like an agent that doesn't exist: `GET /api/agents` leaves it out, the agent, version, workspace, and schedule routes for it answer `404`, and the memory routes answer as they would for a missing agent. Changing its model at runtime with `POST /api/agents/:agentId/model` needs edit access. `POST /api/agents/:agentId/clone` makes the caller the owner of a private clone and ignores an `authorId` in the body. + ## Programmatic access Everything available in Studio is also available programmatically through [`mastra.getEditor()`](/reference/core/getEditor), the REST API, or the Client SDK. Use it to script bulk updates or seed stored configurations from code. It can also power automation that tunes agents based on [evaluation results](/docs/evals/experiments). diff --git a/docs/src/content/en/docs/studio/overview.mdx b/docs/src/content/en/docs/studio/overview.mdx index 0b3328a8425..44d4f8b1b32 100644 --- a/docs/src/content/en/docs/studio/overview.mdx +++ b/docs/src/content/en/docs/studio/overview.mdx @@ -84,7 +84,7 @@ See [processors](/docs/agents/processors) and [guardrails](/docs/agents/guardrai ### MCP servers -List the MCP servers attached to your Mastra instance and explore their available tools. +List the MCP servers attached to your Mastra instance and explore their available tools. The list starts with **Mastra (built-in)**, the [built-in MCP server](/docs/server/mcp#in-studio) at `/api/mcp`, with its endpoint URL, whether it needs a token, and setup for Claude Code, Cursor, VS Code, and the MCP Inspector. ### Tools diff --git a/docs/src/content/en/reference/auth/auth0.mdx b/docs/src/content/en/reference/auth/auth0.mdx index 2e0524b14ec..f7cfd2b5d1a 100644 --- a/docs/src/content/en/reference/auth/auth0.mdx +++ b/docs/src/content/en/reference/auth/auth0.mdx @@ -120,6 +120,8 @@ The `Auth0User` type used in the `authorizeUser` function corresponds to the dec The exact properties available depend on your Auth0 configuration, scopes requested, and any custom claims you've configured. +The authenticated user's `id` is the token's `id` claim, or its `sub` claim when the token has no `id`. RBAC looks up roles by this `id`, and it owns the records the user creates unless `mapUserToResourceId` is set. See [user IDs from JWT providers](/docs/guides/authentication-identity#user-ids-from-jwt-providers). + ## Related [MastraAuthAuth0 Class](/integrations/auth/auth0) diff --git a/docs/src/content/en/reference/auth/clerk.mdx b/docs/src/content/en/reference/auth/clerk.mdx index d05fa247904..4fdb4c26c98 100644 --- a/docs/src/content/en/reference/auth/clerk.mdx +++ b/docs/src/content/en/reference/auth/clerk.mdx @@ -47,6 +47,10 @@ export const mastra = new Mastra({ }) ``` +## User ID + +The authenticated user's `id` is the token's `id` claim, or its `sub` claim when the token has no `id`. RBAC looks up roles by this `id`, and it owns the records the user creates unless `mapUserToResourceId` is set. See [user IDs from JWT providers](/docs/guides/authentication-identity#user-ids-from-jwt-providers). + ## Constructor parameters ` | `message*`, `threadId`, `resourceId` | `POST /agents/:agentId/generate` | `agents:execute` | + +- `list_agents` returns each agent's `id`, `name`, and `description`. `query` keeps agents whose id or name contains the text. +- `call_agent` returns the reply text and the `threadId` to pass back to continue the conversation. +- `agent_` is added for each agent listed in `server.mcp.featured.agents`. +- When the caller can see up to `enumLimit` agents (25 by default), `agentId` lists the allowed ids. + +## `workflows` + +| Tool | Arguments | Route | Permission | +| - | - | - | - | +| `list_workflows` | `query` | `GET /workflows` | `workflows:read` | +| `get_workflow` | `workflowId*` | `GET /workflows/:workflowId` | `workflows:read` | +| `start_workflow` | `workflowId*`, `inputData`, `runId` | `POST /workflows/:workflowId/start-async` | `workflows:execute` | +| `get_workflow_run` | `workflowId*`, `runId*`, `fields` | `GET /workflows/:workflowId/runs/:runId` | `workflows:read` | +| `resume_workflow_run` | `workflowId*`, `runId*`, `step`, `resumeData` | `POST /workflows/:workflowId/resume-async` | `workflows:execute` | +| `cancel_workflow_run` | `workflowId*`, `runId*` | `POST /workflows/:workflowId/runs/:runId/cancel` | `workflows:execute` | +| `workflow_` | The workflow's input schema | `POST /workflows/:workflowId/start-async` | `workflows:execute` | + +- `start_workflow`, `resume_workflow_run`, and `workflow_` wait for the run to finish or suspend. A suspended run returns `status: 'suspended'`, its `runId`, `suspendPayload`, and `suspendedSteps`. +- `get_workflow_run` takes `fields` as a comma-separated subset of `result`, `error`, `payload`, `steps`, and `activeStepsPath`. +- `cancel_workflow_run` carries the MCP `destructiveHint` annotation. +- `workflow_` is added for each workflow listed in `server.mcp.featured.workflows`. When the input schema isn't an object, the tool takes it as `inputData`. + +## `tools` + +When the caller can see up to `enumLimit` tools and may call them, each tool gets its own entry: + +| Tool | Arguments | Route | Permission | +| - | - | - | - | +| `tool_` | The tool's input schema | `POST /tools/:toolId/execute` | `tools:execute` | + +Above `enumLimit`, or when the caller can't call tools (`readOnly: true` or no `tools:execute`), operation tools replace them. `call_tool` is only offered when the caller can call tools: + +| Tool | Arguments | Route | Permission | +| - | - | - | - | +| `list_tools` | `query` | `GET /tools` | `tools:read` | +| `get_tool` | `toolId*` | `GET /tools/:toolId` | `tools:read` | +| `call_tool` | `toolId*`, `data` | `POST /tools/:toolId/execute` | `tools:execute` | + +A `tool_` entry uses the tool's own `mcp.annotations` when the tool defines them. + +## `memory` + +| Tool | Arguments | Route | Permission | +| - | - | - | - | +| `list_threads` | `agentId`, `resourceId`, `page`, `perPage` | `GET /memory/threads` | `memory:read` | +| `get_thread` | `threadId*`, `agentId` | `GET /memory/threads/:threadId` | `memory:read` | +| `list_messages` | `threadId*`, `agentId`, `page`, `perPage` | `GET /memory/threads/:threadId/messages` | `memory:read` | +| `search_memory` | `agentId*`, `searchQuery*`, `resourceId`, `threadId`, `limit` | `GET /memory/search` | `memory:read` | +| `get_memory_status` | `agentId*`, `resourceId`, `threadId` | `GET /memory/status`, `GET /memory/config` | `memory:read` | +| `get_observations` | `agentId*`, `threadId`, `resourceId`, `waitForPending` | `GET /memory/observational-memory` | `memory:read` | +| `create_thread` | `agentId*`, `resourceId`, `title`, `metadata`, `threadId` | `POST /memory/threads` | `memory:write` | +| `update_thread` | `threadId*`, `agentId*`, `title`, `metadata` | `PATCH /memory/threads/:threadId` | `memory:write` | +| `clone_thread` | `threadId*`, `agentId*`, `newThreadId`, `title`, `metadata`, `messageLimit` | `POST /memory/threads/:threadId/clone` | `memory:execute` | +| `save_messages` | `agentId*`, `messages*` | `POST /memory/save-messages` | `memory:write` | + +- `resourceId` defaults to the caller when `server.auth` sets `mapUserToResourceId`, and a caller can't read or write another resource's threads, messages, or Observational Memory. Without `mapUserToResourceId`, the tools use the `resourceId` the client sends, so set `mapUserToResourceId` to keep memory private. [FGA](/docs/auth/fga) protects threads, but `get_observations` called with only a `resourceId` isn't covered by the default FGA routes. +- `get_observations` reads resource-scoped Observational Memory when `threadId` is left out. `waitForPending: true` waits up to 30 seconds for pending observations, and is only offered when the caller may call `POST /memory/observational-memory/buffer-status`, which needs `memory:write`. +- `search_memory` returns up to 20 results unless `limit` is set. + +## `observability` + +| Tool | Arguments | Route | Permission | +| - | - | - | - | +| `query_traces` | `timeRange*`, `where`, `textSearch`, `rootSource`, `group`, `orderBy`, `page` | `POST /observability/traces/query` | `observability:read` | +| `aggregate_traces` | `timeRange*`, `measures*`, `where`, `groupBy`, `interval`, `having`, `orderBy`, `limit` | `POST /observability/traces/aggregate` | `observability:read` | +| `query_spans` | `timeRange*`, `where`, `textSearch`, `orderBy`, `page` | `POST /observability/spans/query` | `observability:read` | +| `aggregate_spans` | `timeRange*`, `measures*`, `where`, `groupBy`, `interval`, `having`, `orderBy`, `limit` | `POST /observability/spans/aggregate` | `observability:read` | +| `query_threads` | `timeRange*`, `where`, `orderBy`, `page` | `POST /observability/threads/query` | `observability:read` | +| `get_trace_query_fields` | `timeRange*`, `predicateScope*`, `search`, `limit` | `POST /observability/traces/query/fields` | `observability:read` | +| `get_trace_query_values` | `timeRange*`, `predicateScope*`, `path*`, `search`, `limit` | `POST /observability/traces/query/values` | `observability:read` | +| `list_traces` | Filters such as `entityType`, `entityName`, `status`, `traceId`, `threadId`, `dateRange`, plus `page`, `perPage`, `field`, `direction` | `GET /observability/traces` | `observability:read` | +| `get_trace` | `traceId*`, `offset` | `GET /observability/traces/:traceId/light` | `observability:read` | +| `get_span` | `traceId*`, `spanId*` | `GET /observability/traces/:traceId/spans/:spanId` | `observability:read` | +| `get_trace_trajectory` | `traceId*` | `GET /observability/traces/:traceId/trajectory` | `observability:read` | +| `list_logs` | Filters such as `level`, `traceId`, `entityName`, `threadId`, `timestamp`, plus `page`, `perPage`, `direction` | `GET /observability/logs` | `observability:read` | + +- A store that supports trace queries serves the query and aggregate tools and not `list_traces`. A store without them serves `list_traces` instead. `list_logs` is served only when the store implements logs. +- `predicateScope` is `trace`, `spans`, `scores`, or `feedback`. `interval` is `1m`, `5m`, `15m`, `1h`, or `1d`. +- `get_trace` returns light span records. Pass the returned `nextOffset` as `offset` to read the rest of a cut trace. + +## `observability_analytics` + +| Tool | Arguments | Route | Permission | +| - | - | - | - | +| `list_scores` | Filters such as `scorerId`, `traceId`, `entityName`, `timestamp`, plus `page`, `perPage`, `field`, `direction` | `GET /observability/scores` | `observability:read` | +| `analyze_scores` | `op*`, `scorerId*`, `scoreSource`, `aggregation`, `filters`, `comparePeriod`, `groupBy`, `interval`, `percentiles` | `POST /observability/scores/` | `observability:read` | +| `list_feedback` | Filters such as `feedbackType`, `traceId`, `reviewStatus`, `timestamp`, plus `page`, `perPage`, `direction` | `GET /observability/feedback` | `observability:read` | +| `analyze_feedback` | `op*`, `feedbackType*`, `feedbackSource`, `aggregation`, `filters`, `comparePeriod`, `groupBy`, `interval`, `percentiles` | `POST /observability/feedback/` | `observability:read` | +| `analyze_metrics` | `op*`, `name*`, `aggregation`, `distinctColumn`, `filters`, `comparePeriod`, `groupBy`, `limit`, `orderDirection`, `interval`, `percentiles` | `POST /observability/metrics/` | `observability:read` | +| `list_metric_names` | `metricName`, `labelKey`, `prefix`, `limit` | `GET /observability/discovery/metric-names`, `metric-label-keys`, `metric-label-values` | `observability:read` | + +- `op` is `aggregate`, `breakdown`, `timeseries`, or `percentiles`, and selects the route the tool calls. +- `aggregation` is `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, or `last`. `comparePeriod` is `previous_period`, `previous_day`, or `previous_week`. +- `list_metric_names` lists metric names. With `metricName`, it lists that metric's label keys. With `metricName` and `labelKey`, it lists that label's values. +- Each tool is served only when the store implements the matching scores, feedback, or metrics queries. + +## `stored_agents` + +| Tool | Arguments | Route | Permission | +| - | - | - | - | +| `list_available_models` | None | `GET /editor/builder/models/available` | `stored-agents:read` | +| `list_stored_agents` | `status`, `page`, `perPage` | `GET /stored/agents` | `stored-agents:read` | +| `get_stored_agent` | `storedAgentId*` | `GET /stored/agents/:storedAgentId` | `stored-agents:read` | +| `create_stored_agent` | `name*`, `instructions*`, `model`, `tools`, `memory`, `visibility`, `autoPublish`, `id`, and the other stored agent fields | `POST /stored/agents` | `stored-agents:write` | +| `update_stored_agent` | `storedAgentId*`, any stored agent field, `changeMessage`, `autoPublish` | `PATCH /stored/agents/:storedAgentId` | `stored-agents:write` | + +- `list_stored_agents` returns published agents unless `status` is `draft` or `archived`, 100 per page by default. +- `create_stored_agent` and `update_stored_agent` publish the change unless `autoPublish` is `false`. A created agent is owned by the caller and private unless `visibility` is `public`. See [stored agent visibility](/docs/studio/editor#visibility). +- When the agent builder restricts models, both tools reject models it doesn't allow. `list_available_models` returns the allowed models. + +## Related + +- [Built-in MCP server](/docs/server/mcp) +- [`server.mcp` configuration reference](/reference/configuration#servermcp) +- [Server routes](/reference/server/routes) +- [`dispatchRoute()`](/reference/server/dispatch-route) diff --git a/docs/src/content/en/reference/sidebars.js b/docs/src/content/en/reference/sidebars.js index 5fe58d95a09..6f6e390565a 100644 --- a/docs/src/content/en/reference/sidebars.js +++ b/docs/src/content/en/reference/sidebars.js @@ -698,6 +698,7 @@ const sidebars = { label: 'Server', collapsed: true, items: [ + { type: 'doc', id: 'server/builtin-mcp-tools', label: 'Built-in MCP tools' }, { type: 'doc', id: 'server/create-route', label: 'createRoute()' }, { type: 'doc', id: 'server/dispatch-route', label: 'dispatchRoute()' }, { type: 'doc', id: 'server/elysia-adapter', label: 'Elysia Adapter' }, diff --git a/docs/src/content/en/reference/tools/mcp-server.mdx b/docs/src/content/en/reference/tools/mcp-server.mdx index a52df55c2b9..77340b9686e 100644 --- a/docs/src/content/en/reference/tools/mcp-server.mdx +++ b/docs/src/content/en/reference/tools/mcp-server.mdx @@ -11,6 +11,8 @@ The `MCPServer` class provides the functionality to expose your existing Mastra Note that if you only need to use your tools or agents directly within your Mastra application, you don't necessarily need to create an MCP server. This API is specifically for exposing your Mastra tools and agents to _external_ MCP clients. +To expose every agent, workflow, and tool on your Mastra app without defining a server, use the [built-in MCP server](/docs/server/mcp) at `/api/mcp` instead. It builds its tool list per caller and runs each call through the matching HTTP route's auth and permission checks. Use `MCPServer` to publish a chosen set of tools and agents with your own prompts and resources, or to serve over stdio. + It supports the [stdio (subprocess) and Streamable HTTP MCP transports](https://modelcontextprotocol.io/docs/concepts/transports) of the MCP `2026-07-28` revision. :::note From 175b4b5194bd74d82a79c2567aec44ef0cfafa80 Mon Sep 17 00:00:00 2001 From: Tyler Barnes Date: Thu, 12 Nov 2026 14:52:04 -0700 Subject: [PATCH 006/239] fix(core): Knowledge scope values are one encoded segment (#30019) Knowledge scope patterns let the last `$` value take the rest of an address, so `org:acme:viewer` counted as an `org:$orgId` scope. Its holder then got that pattern's rights on what was meant to be a separate scope. Raw ids and escaped ids also had more than one spelling. This makes each `$` value exactly one segment and gives every scope one canonical spelling. ## What changes - A scope value can't contain a raw `:`. Ids with `:`, `/`, `#` or `%` are passed encoded, via the new `encodeKnowledgeScopeId` (`decodeKnowledgeScopeId` reverses it). Raw forms are refused with a message naming the helper. - Agent `scopes` are canonical addresses: `%` is always an escape. - Memory resource and thread ids are bound encoded (`slack:U123` becomes `resource:slack%3AU123`). Knowledge takes identity only from the run's resolved Memory ids, never from `resource:`/`thread:` strings in the run scopes. - Patterns of one type with different segment counts no longer overlap, so `org:$orgId` and `org:$orgId:viewer` can be declared together. - A stored scope row whose address now matches a different declaration than the one it was created under gets none of the new declaration's access: not by exact address, prefix, `belongsTo` lookup or parent-bound role. Holders of the old declaration's prefix grant still read it, as before, without a role. ## Existing data Nothing is rewritten. Ids with a raw colon in the last segment get new addresses, so a run reaches a new, empty scope, and rows at the old address stay unreached. Ids with `/`, `#` or `%` were already encoded and keep their addresses when passed through `encodeKnowledgeScopeId`. Knowledge is in alpha; this is a breaking change for colon ids. ## Testing - New tests cover encoded and raw ids, segment counts, stale rows (exact, prefix, `belongsTo` parent, parent-bound roles) and Memory identity through `resolveAgentScopes`. Each fails on the commit before its fix. - Core Knowledge, storage and agent-scope suites: 412 passed. Server Knowledge handlers: 48 passed. Typecheck, lint and format are clean. - A store written by the previous release, read by this one: `/`, `#`, `%` and literal-escape ids remain readable through `encodeKnowledgeScopeId`; colon ids move. **ELI5:** Knowledge uses labels called scopes to decide who can read which pages. This change makes each label part match exactly one piece of the address, and it requires special characters in IDs to be encoded. This makes access rules predictable, but old alpha data with colons in IDs may no longer be reached. ## Overview This change makes each scope parameter match exactly one address segment. Scope IDs that contain reserved characters must use canonical encoding. The change is breaking for alpha Knowledge users who have colon IDs in the last segment. ## Core changes - **Scope matching** (`declarations.ts`): Patterns match an exact segment count. A final parameter no longer absorbs raw colons. Raw Agent scopes are no longer matched. `knowledgeRunScopes` accepts only canonical addresses that match a declaration, returns them unchanged, and rejects reserved characters that are not encoded. - **Overlap rules** (`declarations.ts`): Patterns overlap only when they share a type, have no conflicting literals, and have equal segment counts. - **Encoding** (`scope-address.ts`): - `encodeKnowledgeScopeValue` and `decodeKnowledgeScopeValue` always escape `%`, `/`, `#`, and `:`. The `final` argument is removed. - New experimental helpers `encodeKnowledgeScopeId` and `decodeKnowledgeScopeId` encode and decode one ID segment. They are exported from `index.ts`. - **Memory identity** (`run.ts`): Resource and thread scopes are built by binding Memory IDs through `knowledgeScopeAddress`. The generated addresses must match compiled declarations. A mismatch raises `KnowledgeDeclarationError`. The result is the deduplicated union of raw and Memory-derived scopes. - **Stale rows** (`scope-runtime.ts`): A stored scope is current only when it has no declaration key or its address matches that declaration. Stale rows are excluded from `belongsTo` parent resolution, final readable addresses, and `roleOn`. `explainAccess` returns no grants for a stale target. Materialization rejects a stored scope whose declaration no longer matches its address. ## Mastra Code and Factory changes - `knowledge-scope.ts` encodes Factory organization and project IDs once, as single canonical segments. A host tag of the same type with a different value is rejected. - `knowledge-inspector.ts` encodes resource and thread IDs before calling `readScopeFor`. It no longer uses the local `canonical` helper. Session tags are unchanged. - `factory/src/routes/knowledge.ts` encodes organization and project IDs before building `org:` and `project:` principals. ## Data compatibility - No stored data is rewritten. - IDs with a raw colon in the last segment map to new addresses. Existing rows at old addresses are not reached. - IDs that contain `/`, `#`, or `%` keep their addresses when encoded. - Stale rows do not gain access from a new matching declaration. A prefix grant from the original declaration can still include those rows in reads, as tested in `legacy-scope-rows.test.ts`. ## Documentation - Scope declaration docs say each `$param` matches one segment. They describe compatibility effects for alpha scopes and the new overlap rule. - Memory scope docs describe `encodeKnowledgeScopeId` and `decodeKnowledgeScopeId`. They state that alpha scopes with a raw colon in the last segment are not migrated. - `explainAccess` docs describe `runScopes` as canonical addresses. - A changeset marks a minor `@mastra/core` release. Changesets for `@mastra/code-sdk` and `@mastra/factory` are patch releases. ## Tests - New and updated tests cover encoded and raw IDs, segment counts, stale rows, and Memory identity through `resolveAgentScopes`. - A new helper, `agentRunContext`, is used by test files. - The author reports 412 passing core Knowledge, storage, and agent-scope tests. The author also reports 48 passing server Knowledge handler tests, and clean typecheck, lint, and format. These results are not verified here. CI status is not available. ## Scope of change - Files changed: 24 - Lines added: 549 - Lines removed: 116 - Review severity counts: not available --------- Co-authored-by: remy-builder[bot] <324360501+remy-builder[bot]@users.noreply.github.com> --- .../knowledge-scope-values-no-colons.md | 22 +++ .../mastracode-knowledge-canonical-scopes.md | 6 + .../en/docs/knowledge/scopes-and-access.mdx | 2 +- .../reference/knowledge/knowledge-class.mdx | 2 +- .../knowledge/knowledge-memory-scopes.mdx | 48 ++++++- .../knowledge/scope-declarations.mdx | 14 +- .../factory/src/routes/knowledge.test.ts | 24 +++- mastracode/factory/src/routes/knowledge.ts | 8 +- .../sdk/src/knowledge-inspector.test.ts | 13 ++ mastracode/sdk/src/knowledge-inspector.ts | 14 +- mastracode/sdk/src/knowledge-scope.test.ts | 11 ++ mastracode/sdk/src/knowledge-scope.ts | 16 ++- .../knowledge/__tests__/agent-run-context.ts | 16 +++ .../knowledge/__tests__/declarations.test.ts | 85 ++++++++---- .../knowledge/__tests__/lazy-scopes.test.ts | 8 +- .../__tests__/legacy-scope-rows.test.ts | 125 ++++++++++++++++++ .../__tests__/memory-identity.test.ts | 64 +++++++++ .../knowledge/__tests__/page-tools.test.ts | 20 +-- .../src/knowledge/__tests__/semantic.test.ts | 10 +- packages/core/src/knowledge/declarations.ts | 38 +++--- packages/core/src/knowledge/index.ts | 3 +- packages/core/src/knowledge/run.ts | 33 ++++- packages/core/src/knowledge/scope-address.ts | 28 +++- packages/core/src/knowledge/scope-runtime.ts | 55 +++++++- 24 files changed, 549 insertions(+), 116 deletions(-) create mode 100644 .changeset/knowledge-scope-values-no-colons.md create mode 100644 .changeset/mastracode-knowledge-canonical-scopes.md create mode 100644 packages/core/src/knowledge/__tests__/agent-run-context.ts create mode 100644 packages/core/src/knowledge/__tests__/legacy-scope-rows.test.ts create mode 100644 packages/core/src/knowledge/__tests__/memory-identity.test.ts diff --git a/.changeset/knowledge-scope-values-no-colons.md b/.changeset/knowledge-scope-values-no-colons.md new file mode 100644 index 00000000000..c62423e8f8f --- /dev/null +++ b/.changeset/knowledge-scope-values-no-colons.md @@ -0,0 +1,22 @@ +--- +'@mastra/core': minor +--- + +**Breaking (Knowledge alpha):** a `$param` in a Knowledge scope pattern now matches exactly one segment, so scope values can no longer contain a raw `:`. Before, the last param took the rest of the address, so `org:acme:viewer` counted as an `org:$orgId` scope and its holder got that pattern's `self` rights there. + +- Agent `scopes` are canonical addresses. An id containing `:`, `/`, `#` or `%` must be encoded with the new `encodeKnowledgeScopeId`. The raw form (e.g. `org:a:b` against `org:$orgId`) fails with "does not match a declared scope type", and `%` is always read as an escape, so each scope has one spelling. +- Memory ids are bound encoded: resource `slack:U123` becomes `resource:slack%3AU123`. +- Patterns of one type with different segment counts no longer overlap, so `org:$orgId` and `org:$orgId:viewer` can be declared side by side. +- `decodeKnowledgeScopeId` reads an id back from one segment of an address. + +```ts +import { encodeKnowledgeScopeId } from '@mastra/core/knowledge'; + +const scope = `org:${encodeKnowledgeScopeId('auth0|a:b')}`; // 'org:auth0|a%3Ab', pass this in Agent scopes +``` + +No data is rewritten: + +- **Ids with a colon in the last segment get new addresses.** Before, the last segment kept a raw `:` (`resource:slack:U123`); now it is encoded (`resource:slack%3AU123`), so a run reaches a new, empty scope, and pages, pins and notes stored under the old address stay there unreached. Nothing moves them. +- **Every other id keeps its address if you pass it through `encodeKnowledgeScopeId`.** `/`, `#` and `%` were already encoded the same way, so `org:${encodeKnowledgeScopeId('a/b')}` reaches rows stored from the raw `org:a/b`. Passing the old raw string unchanged does not: `org:a/b` is refused, and a raw scope that happened to contain an escape (`org:a%3Ab`, once stored as `org:a%253Ab`) now means the id `a:b`. +- **Stale rows get nothing from their new match.** A stored scope row whose address now matches a different declaration than the one it was created under (e.g. `org:acme:viewer` created under `org:$orgId`, once `org:$orgId:viewer` is declared) gets none of the new declaration's access. It is never a `belongsTo` parent, and using it as a scope of the new declaration fails with an error. Prefix grants of the declaration it was created under still let their holders read it, as before, without a role on it. diff --git a/.changeset/mastracode-knowledge-canonical-scopes.md b/.changeset/mastracode-knowledge-canonical-scopes.md new file mode 100644 index 00000000000..b133bce99cb --- /dev/null +++ b/.changeset/mastracode-knowledge-canonical-scopes.md @@ -0,0 +1,6 @@ +--- +'@mastra/code-sdk': patch +'@mastra/factory': patch +--- + +Mastra Code's Knowledge scopes now use canonical addresses, matching `@mastra/core`'s one-segment scope values. Factory sessions hold their org and project ids encoded (`org:acme%3Aeu` for org `acme:eu`), and the `/knowledge` inspector and Factory Knowledge routes read the same addresses the code agent writes, instead of encoding host scopes a second time. diff --git a/docs/src/content/en/docs/knowledge/scopes-and-access.mdx b/docs/src/content/en/docs/knowledge/scopes-and-access.mdx index 6b98e73c523..df8aa9569a8 100644 --- a/docs/src/content/en/docs/knowledge/scopes-and-access.mdx +++ b/docs/src/content/en/docs/knowledge/scopes-and-access.mdx @@ -130,7 +130,7 @@ await support.generate('How do I handle a chargeback?', { }) ``` -With Memory, the run also holds the `resource:` and `thread:` scopes from the `memory` option, here `resource:dana` and `thread:ticket-91`. A run can hold only one of each. If you pass a `resource:` scope that differs from `memory.resource`, the run fails. Pass raw IDs. Knowledge encodes them for you. +With Memory, the run also holds the `resource:` and `thread:` scopes from the `memory` option, here `resource:dana` and `thread:ticket-91`. A run can hold only one of each. If you pass a `resource:` scope that differs from `memory.resource`, the run fails. `resource:` and `thread:` scopes take Memory's IDs unchanged, and Knowledge encodes them. Every other scope is a canonical address: encode an ID that contains `:`, `/`, `#` or `%` with [`encodeKnowledgeScopeId()`](/reference/knowledge/knowledge-memory-scopes#encodeknowledgescopeid), such as `` `org:${encodeKnowledgeScopeId(user.orgId)}` ``. ### For one agent diff --git a/docs/src/content/en/reference/knowledge/knowledge-class.mdx b/docs/src/content/en/reference/knowledge/knowledge-class.mdx index 6b155481365..e354fff7b8e 100644 --- a/docs/src/content/en/reference/knowledge/knowledge-class.mdx +++ b/docs/src/content/en/reference/knowledge/knowledge-class.mdx @@ -159,7 +159,7 @@ explainAccess( ): Promise ``` -Explains why a run holding `runScopes` can or can't reach a scope or page. `runScopes` are raw run scopes, as you'd pass to an agent. `target.page` takes a page ID or a page path such as `org:acme#policies/refund`. +Explains why a run holding `runScopes` can or can't reach a scope or page. `runScopes` are canonical addresses, including `resource:` and `thread:` (`resource:slack%3AU123` for Memory resource `slack:U123`). `target.page` takes a page ID or a page path such as `org:acme#policies/refund`. ```typescript await knowledge.explainAccess(['org:acme'], { page: 'team:acme:support#refunds' }) diff --git a/docs/src/content/en/reference/knowledge/knowledge-memory-scopes.mdx b/docs/src/content/en/reference/knowledge/knowledge-memory-scopes.mdx index b8021c83b13..de74333787a 100644 --- a/docs/src/content/en/reference/knowledge/knowledge-memory-scopes.mdx +++ b/docs/src/content/en/reference/knowledge/knowledge-memory-scopes.mdx @@ -79,9 +79,9 @@ knowledgeMemoryScopes({ org: 'workspace:$workspaceId', orgRole: 'contributor' }) knowledgeScopeAddress(pattern: string, params: Record): string ``` -Builds a canonical scope address from a pattern and raw parameter values. Use it in host code for Knowledge APIs, `pinnedContext` entries and page references. +Builds a canonical scope address from a pattern and raw parameter values. Use it in host code for agent scopes, Knowledge APIs, `pinnedContext` entries and page references. -Inside values, `%`, `/` and `#` are encoded as `%25`, `%2F` and `%23`. `:` is encoded as `%3A` in every parameter except the last. It throws when a parameter is missing or empty. +Inside every value, `%`, `/`, `#` and `:` are encoded as `%25`, `%2F`, `%23` and `%3A`. Each value fills exactly one segment. It throws when a parameter is missing or empty. ```typescript import { knowledgeScopeAddress } from '@mastra/core/knowledge' @@ -90,14 +90,50 @@ knowledgeScopeAddress('resource:$resourceId', { resourceId: 'acme/dana' }) // 'resource:acme%2Fdana' knowledgeScopeAddress('team:$orgId:$teamId', { orgId: 'a:b', teamId: 'c:d' }) -// 'team:a%3Ab:c:d' +// 'team:a%3Ab:c%3Ad' ``` -:::note +## `encodeKnowledgeScopeId()` -Don't pass the result as an agent scope. Agent scopes take raw IDs (`resource:acme/dana`), and Knowledge encodes them at run start. See [set a run's scopes](/docs/knowledge/scopes-and-access#set-a-runs-scopes). +```typescript oxfmt:false +encodeKnowledgeScopeId(id: string): string +``` -::: +Encodes one ID, such as a tenant or user ID, for one segment of a scope address. It applies the same encoding as `knowledgeScopeAddress()`. Use it when you build an address with a template string: + +```typescript +import { encodeKnowledgeScopeId } from '@mastra/core/knowledge' + +const scope = `org:${encodeKnowledgeScopeId('auth0|a:b')}` +// 'org:auth0|a%3Ab' +``` + +## `decodeKnowledgeScopeId()` + +```typescript oxfmt:false +decodeKnowledgeScopeId(segment: string): string | null +``` + +Returns the ID in one segment of a scope address. It returns `null` when the segment isn't canonically encoded, for example when it holds a raw `:` or a lowercase escape such as `%3a`. + +```typescript +import { decodeKnowledgeScopeId } from '@mastra/core/knowledge' + +decodeKnowledgeScopeId('slack%3AU123') // 'slack:U123' +decodeKnowledgeScopeId('a:b') // null +``` + +## Agent scopes + +Agent scopes are canonical addresses. Encode any ID that contains `:`, `/`, `#` or `%`, with `encodeKnowledgeScopeId()` or `knowledgeScopeAddress()`. A raw ID, such as `org:a:b` for org `a:b`, fails at run start: + +```text +Knowledge run scope "org:a:b" does not match a declared scope type. Declare it in Knowledge `scopes` (for Memory's resource:/thread: scopes, spread `...knowledgeMemoryScopes()`), and encode ids containing ":", "/", "#" or "%" with encodeKnowledgeScopeId. +``` + +`resource:` and `thread:` agent scopes are the exception. They set the run's Memory resource and thread, so they take Memory's raw IDs, and Knowledge encodes them. A run with Memory resource `slack:U123` holds `resource:slack%3AU123`. See [set a run's scopes](/docs/knowledge/scopes-and-access#set-a-runs-scopes). + +Scopes stored by earlier alpha releases with a raw `:` in their last segment aren't moved to the encoded address. See [Patterns and params](/reference/knowledge/scope-declarations#patterns-and-params). ## Related diff --git a/docs/src/content/en/reference/knowledge/scope-declarations.mdx b/docs/src/content/en/reference/knowledge/scope-declarations.mdx index bc6c23036d0..9fbf3a364bb 100644 --- a/docs/src/content/en/reference/knowledge/scope-declarations.mdx +++ b/docs/src/content/en/reference/knowledge/scope-declarations.mdx @@ -100,9 +100,17 @@ export const knowledge = new Knowledge({ A key such as `team:$orgId:$teamId` is a pattern. The text before the first `:` is the type, and each `$name` segment is a param. The address `team:acme:support` matches it with `$orgId = acme` and `$teamId = support`. -The last param takes the rest of the value, so `resource:$resourceId` matches `resource:user:123` with `$resourceId = user:123`. Memory ids that contain `:` keep working. +Each param matches exactly one segment, so an address has as many segments as its pattern. `resource:user:123` doesn't match `resource:$resourceId`. An ID that contains `:`, `/`, `#` or `%` is encoded into one segment, so user `user:123` is `resource:user%3A123`. Build addresses with [`encodeKnowledgeScopeId()` or `knowledgeScopeAddress()`](/reference/knowledge/knowledge-memory-scopes#encodeknowledgescopeid). Memory IDs are encoded for you. -A type can have several patterns only when no address can match two of them. Each pair must have different literal text at the same position: +:::warning[Scopes stored by earlier alpha releases] + +Earlier releases let the last param take the rest of the address, raw colons included. A scope stored that way, such as `resource:slack:U123` for Memory resource `slack:U123`, now has a new address, `resource:slack%3AU123`. Runs reach the new, empty scope. Pages, pins and notes under the old address stay in storage, but runs with that Memory resource no longer reach them, and Knowledge doesn't move them. + +A stored scope whose address now matches a different pattern, such as `org:acme:viewer` stored as an `org:$orgId` scope before you declared `org:$orgId:viewer`, gets no rules from the new pattern. Using it as a scope of the new pattern throws. + +::: + +A type can have several patterns only when no address can match two of them. Patterns with different numbers of segments never overlap. Patterns with the same number must have different literal text at the same position: ```typescript oxfmt:false scopes: { @@ -117,7 +125,7 @@ Overlapping patterns fail at startup. There's no precedence between them: Knowledge scope patterns "role:$orgId:$role" and "role:$orgId:admin" overlap; patterns of a type must be pairwise disjoint. ``` -A pattern ending in a param overlaps a longer one with the same start, so `kb:$orgId` and `kb:$orgId:public` overlap too. Use two types, such as `kb-public:$orgId` and `kb-internal:$orgId`. +`kb:$orgId` and `kb:$orgId:public` can be declared together, because `kb:acme` and `kb:acme:public` have different numbers of segments. Each is its own scope with its own rules. Holding `kb:acme` gives no role on `kb:acme:public` unless a rule on `kb:$orgId:public` names `kb:$orgId`. ## Rules diff --git a/mastracode/factory/src/routes/knowledge.test.ts b/mastracode/factory/src/routes/knowledge.test.ts index 8bf4bfdfb7f..d3e8d64272b 100644 --- a/mastracode/factory/src/routes/knowledge.test.ts +++ b/mastracode/factory/src/routes/knowledge.test.ts @@ -1,4 +1,4 @@ -import { Knowledge } from '@mastra/core/knowledge'; +import { encodeKnowledgeScopeId, Knowledge } from '@mastra/core/knowledge'; import type { KnowledgeStorage } from '@mastra/core/storage'; import { InMemoryStore } from '@mastra/core/storage'; import { Hono } from 'hono'; @@ -32,11 +32,13 @@ async function createHarness( options: { user?: { workosId: string; organizationId?: string } | null; declarations?: ConstructorParameters[0]['scopes']; + orgId?: string; } = {}, ) { + const orgId = options.orgId ?? ORG; const factory = await createFactoryStorageForTests(); - const project = await factory.projects.create({ orgId: ORG, userId: 'user-1', input: { name: 'P' } }); - const other = await factory.projects.create({ orgId: ORG, userId: 'user-1', input: { name: 'Q' } }); + const project = await factory.projects.create({ orgId, userId: 'user-1', input: { name: 'P' } }); + const other = await factory.projects.create({ orgId, userId: 'user-1', input: { name: 'Q' } }); const foreign = await factory.projects.create({ orgId: OTHER_ORG, userId: 'user-2', input: { name: 'X' } }); const knowledge = new Knowledge({ @@ -48,9 +50,9 @@ async function createHarness( const scope = async (address: string, declaration: string, name: string, parentId?: string) => (await store.materializeScope({ address, declaration, name, provenance: host, ...(parentId ? { parentId } : {}) })) .scope; - const org = await scope(`org:${ORG}`, 'org:$orgId', 'Org one'); - const p = await scope(`project:${project.id}`, 'project:$projectId', 'Project P', org.id); - const q = await scope(`project:${other.id}`, 'project:$projectId', 'Project Q', org.id); + const org = await scope(`org:${encodeKnowledgeScopeId(orgId)}`, 'org:$orgId', 'Org one'); + const p = await scope(`project:${encodeKnowledgeScopeId(project.id)}`, 'project:$projectId', 'Project P', org.id); + const q = await scope(`project:${encodeKnowledgeScopeId(other.id)}`, 'project:$projectId', 'Project Q', org.id); const thread = await scope('thread:t-1', 'thread:$threadId', 'Session T', p.id); const otherOrg = await scope(`org:${OTHER_ORG}`, 'org:$orgId', 'Org two'); const handbook = await store.createPage({ parentId: org.id, name: 'Handbook', provenance: host }); @@ -67,7 +69,7 @@ async function createHarness( }); const app = new Hono(); - const user = options.user === undefined ? { workosId: 'user-1', organizationId: ORG } : options.user; + const user = options.user === undefined ? { workosId: 'user-1', organizationId: orgId } : options.user; app.use('*', async (context, next) => { if (user) context.set('factoryAuthUser' as never, user as never); await next(); @@ -140,6 +142,14 @@ describe('Factory Knowledge routes on the page store', () => { expect(names(underOrg.body.pages)).toEqual(['Handbook', 'Project P']); }); + it('reads an org whose id contains a colon at its encoded address, as Factory sessions write it', async () => { + const h = await createHarness({ orgId: 'org:eu' }); + expect(h.org.address).toBe('org:org%3Aeu'); + const graph = await h.get('/graph'); + expect(graph.status).toBe(200); + expect(names(graph.body.pages)).toEqual(['Deploy runbook', 'Handbook', 'Org one', 'Project P']); + }); + it('reads the other project through its own route', async () => { const h = await createHarness(); const graph = await h.get('/graph', h.otherProjectId); diff --git a/mastracode/factory/src/routes/knowledge.ts b/mastracode/factory/src/routes/knowledge.ts index 64aa1398c82..426b8ee7b1b 100644 --- a/mastracode/factory/src/routes/knowledge.ts +++ b/mastracode/factory/src/routes/knowledge.ts @@ -14,6 +14,7 @@ import type { Knowledge, KnowledgeChangeEvent } from '@mastra/core/knowledge'; import { + encodeKnowledgeScopeId, KnowledgeDeclarationError, listKnowledgeTreeChildren, readKnowledgePage, @@ -145,7 +146,12 @@ export class KnowledgeRoutes extends Route { }; } try { - return { knowledge, store, read: await knowledge.readScopeFor([`org:${tenant.orgId}`, `project:${projectId}`]) }; + // The same canonical addresses a Factory session's runs hold (see the SDK's resolveKnowledgeSessionScopes). + const principals = [ + `org:${encodeKnowledgeScopeId(tenant.orgId)}`, + `project:${encodeKnowledgeScopeId(projectId)}`, + ]; + return { knowledge, store, read: await knowledge.readScopeFor(principals) }; } catch (error) { // The host's Knowledge does not declare the scopes a Factory run holds (`org:` and `project:`): a // deployment misconfiguration, which its session runs hit too. Never fall back to a guessed scope. diff --git a/mastracode/sdk/src/knowledge-inspector.test.ts b/mastracode/sdk/src/knowledge-inspector.test.ts index 918b9f9be52..95f7b0f29fa 100644 --- a/mastracode/sdk/src/knowledge-inspector.test.ts +++ b/mastracode/sdk/src/knowledge-inspector.test.ts @@ -289,6 +289,19 @@ describe('KnowledgeInspector', () => { expect(names(await harness.inspector.listNodes({ level: 'org' }))).toEqual(['Acme handbook', 'P1 plan']); }); + it('reads the same canonical scopes the code agent writes, encoding only Memory ids', async () => { + // Host scopes reach the agent as canonical addresses, so the inspector must not encode them again. + harness = await createHarness({}, ['org:a%3Ab']); + await harness.seed.page('org:a%3Ab', 'Encoded org page'); + expect(names(await harness.inspector.listNodes({ level: 'org' }))).toEqual(['Encoded org page']); + + // A Factory org id with a colon is held encoded, as the agent holds it. + harness = await createHarness({ factoryOrgId: 'acme:eu', factoryProjectId: 'p:1' }, []); + await harness.seed.page('org:acme%3Aeu', 'EU handbook'); + await harness.seed.page('project:p%3A1', 'P1 plan'); + expect(names(await harness.inspector.listNodes({ level: 'org' }))).toEqual(['EU handbook', 'P1 plan']); + }); + it('fails closed when a Factory-owned session has no resolved org', async () => { harness = await createHarness({ factoryProjectId: 'p1' }, []); await expect(harness.inspector.getScopeTree()).rejects.toMatchObject({ code: 'unavailable' }); diff --git a/mastracode/sdk/src/knowledge-inspector.ts b/mastracode/sdk/src/knowledge-inspector.ts index c099f9b6647..1002b7e0952 100644 --- a/mastracode/sdk/src/knowledge-inspector.ts +++ b/mastracode/sdk/src/knowledge-inspector.ts @@ -1,5 +1,5 @@ import type { Session } from '@mastra/core/agent-controller'; -import { knowledgeScopeAddress } from '@mastra/core/knowledge'; +import { encodeKnowledgeScopeId } from '@mastra/core/knowledge'; import type { Knowledge } from '@mastra/core/knowledge'; import type { Mastra } from '@mastra/core/mastra'; import { parseKnowledgeWikilinks } from '@mastra/core/storage'; @@ -224,12 +224,6 @@ function badgeOf(address: string | undefined): KnowledgeInspectorScopeBadge { return { level: address.slice(0, separator), id: address.slice(separator + 1) }; } -/** A session tag in Knowledge's canonical form; every type the session holds has one `$param`. */ -function canonical(tag: string): string { - const separator = tag.indexOf(':'); - return knowledgeScopeAddress(`${tag.slice(0, separator)}:$value`, { value: tag.slice(separator + 1) }); -} - function truncateUtf8(value: string, maxBytes: number): { value: string; truncated: boolean } { const encoded = Buffer.from(value); if (encoded.byteLength <= maxBytes) return { value, truncated: false }; @@ -482,16 +476,16 @@ class ScopedKnowledgeInspector implements KnowledgeInspector { } principals = [...binding.sessionTags]; } else { - principals = [...binding.sessionTags, `resource:${binding.resourceId}`]; + principals = [...binding.sessionTags, `resource:${encodeKnowledgeScopeId(binding.resourceId)}`]; if (level === 'thread') { if (!binding.threadId) { throw new KnowledgeInspectorError('unavailable', 'The active thread does not belong to this project.'); } - principals.push(`thread:${binding.threadId}`); + principals.push(`thread:${encodeKnowledgeScopeId(binding.threadId)}`); } } try { - return { level, read: await this.#knowledge.readScopeFor(principals.map(canonical)) }; + return { level, read: await this.#knowledge.readScopeFor(principals) }; } catch (error) { throw new KnowledgeInspectorError( 'unavailable', diff --git a/mastracode/sdk/src/knowledge-scope.test.ts b/mastracode/sdk/src/knowledge-scope.test.ts index 75cba22899a..3c06a4207a5 100644 --- a/mastracode/sdk/src/knowledge-scope.test.ts +++ b/mastracode/sdk/src/knowledge-scope.test.ts @@ -24,6 +24,17 @@ describe('resolveKnowledgeSessionScopes', () => { }); }); + it('encodes Factory org and project ids into one canonical segment', () => { + expect(resolveKnowledgeSessionScopes({ factoryOrgId: 'acme:eu', factoryProjectId: 'p/1' } as never)).toEqual({ + resolved: true, + scopes: ['org:acme%3Aeu', 'project:p%2F1'], + }); + expect(resolveKnowledgeSessionScopes({ factoryOrgId: 'acme:eu' } as never, ['org:acme%3Aeu'])).toEqual({ + resolved: true, + scopes: ['org:acme%3Aeu'], + }); + }); + it('keeps two Factory projects apart and refuses a host tag that names another org or project', () => { const a = resolveKnowledgeSessionScopes({ factoryOrgId: 'o', factoryProjectId: 'a' } as never); const b = resolveKnowledgeSessionScopes({ factoryOrgId: 'o', factoryProjectId: 'b' } as never); diff --git a/mastracode/sdk/src/knowledge-scope.ts b/mastracode/sdk/src/knowledge-scope.ts index f475d16c069..ec84187dda2 100644 --- a/mastracode/sdk/src/knowledge-scope.ts +++ b/mastracode/sdk/src/knowledge-scope.ts @@ -1,3 +1,5 @@ +import { encodeKnowledgeScopeId } from '@mastra/core/knowledge'; + import type { MastraCodeState } from './schema.js'; /** @@ -18,10 +20,11 @@ function isIdentityTag(tag: string): boolean { * Every Knowledge reader and writer in a session (the code agent, the /knowledge inspector) uses * this, so what the agent writes is what the inspector reads. * - * - Factory sessions require `org:` and `project:`, so projects stay - * isolated. A host tag of the same type with another value is refused. A Factory session with - * no org resolves to nothing (fail closed): a session owner is a user id, never an org. - * - Local sessions act with the host's scopes as given. + * - Factory sessions require `org:` and `project:`, with each id + * encoded into one canonical segment, so projects stay isolated. A host tag of the same type with + * another value is refused. A Factory session with no org resolves to nothing (fail closed): a + * session owner is a user id, never an org. + * - Local sessions act with the host's scopes as given; they are canonical addresses already. */ export function resolveKnowledgeSessionScopes( state: MastraCodeState | undefined, @@ -33,7 +36,10 @@ export function resolveKnowledgeSessionScopes( if (factoryOwned) { if (!orgId) return { resolved: false, reason: 'This Factory session has no resolved organization.' }; - const required = [`org:${orgId}`, ...(projectId ? [`project:${projectId}`] : [])]; + const required = [ + `org:${encodeKnowledgeScopeId(orgId)}`, + ...(projectId ? [`project:${encodeKnowledgeScopeId(projectId)}`] : []), + ]; for (const tag of hostScopes) { const type = tag.slice(0, tag.indexOf(':') + 1); const conflict = required.find(requiredTag => requiredTag.startsWith(type) && requiredTag !== tag); diff --git a/packages/core/src/knowledge/__tests__/agent-run-context.ts b/packages/core/src/knowledge/__tests__/agent-run-context.ts new file mode 100644 index 00000000000..88efac32db6 --- /dev/null +++ b/packages/core/src/knowledge/__tests__/agent-run-context.ts @@ -0,0 +1,16 @@ +import { deriveAgentRunRequestContext, resolveAgentScopes } from '../../agent/scopes'; +import { RequestContext } from '../../request-context'; + +/** + * The tool context a real Agent run hands Knowledge for `scopes`: resolved by `resolveAgentScopes`, + * so `resource:`/`thread:` become the run's Memory ids and only the other scopes stay on the + * request context. + */ +export function agentRunContext(agentId: string, scopes: string[]) { + const requestContext = new RequestContext(); + const resolved = resolveAgentScopes({ requestContext, callScopes: scopes }); + return { + requestContext: deriveAgentRunRequestContext(requestContext, resolved.scopes), + agent: { agentId, resourceId: resolved.resourceId, threadId: resolved.threadId }, + }; +} diff --git a/packages/core/src/knowledge/__tests__/declarations.test.ts b/packages/core/src/knowledge/__tests__/declarations.test.ts index 4c3c6d113b8..c444b6c2ff3 100644 --- a/packages/core/src/knowledge/__tests__/declarations.test.ts +++ b/packages/core/src/knowledge/__tests__/declarations.test.ts @@ -9,6 +9,7 @@ import { knowledgeRunScopes, knowledgeScopeAddress, } from '../declarations'; +import { decodeKnowledgeScopeId, encodeKnowledgeScopeId } from '../index'; const scopes = { ...knowledgeMemoryScopes(), @@ -38,16 +39,39 @@ const scopes = { describe('compileKnowledgeScopes: matching', () => { const compiled = compileKnowledgeScopes(scopes); - it('binds params, with the last param taking the rest of the value', () => { + it('binds params, each one exactly one segment', () => { expect(compiled.match('team:acme:support')).toMatchObject({ declaration: 'team:$orgId:$teamId', params: { orgId: 'acme', teamId: 'support' }, }); - expect(compiled.match('resource:user:123')).toMatchObject({ + expect(compiled.match('resource:user%3A123')).toMatchObject({ declaration: 'resource:$resourceId', params: { resourceId: 'user:123' }, }); - expect(compiled.match('team:acme:support:emea')?.params).toEqual({ orgId: 'acme', teamId: 'support:emea' }); + }); + + it('never lets a param value contain a raw colon, so org:x:viewer is not an org: scope', () => { + expect(compiled.match('resource:user:123')).toBeNull(); + expect(compiled.match('team:acme:support:emea')).toBeNull(); + expect(compiled.match('org:acme:viewer')).toBeNull(); + expect(() => knowledgeRunScopes(compiled, ['org:acme:viewer'])).toThrow(KnowledgeDeclarationError); + }); + + it('lets org:$orgId and org:$orgId:viewer be declared side by side as distinct patterns', () => { + const both = compileKnowledgeScopes({ + 'org:$orgId': { + access: [ + { principal: 'self', role: 'editor' as const }, + { principal: 'org:$orgId:viewer', role: 'viewer' as const }, + ], + }, + 'org:$orgId:viewer': { access: [] }, + }); + expect(both.match('org:acme')?.declaration).toBe('org:$orgId'); + expect(both.match('org:acme:viewer')?.declaration).toBe('org:$orgId:viewer'); + expect(knowledgeRoleOn(both, ['org:acme:viewer'], { address: 'org:acme' })).toBe('viewer'); + expect(knowledgeRoleOn(both, ['org:acme:viewer'], { address: 'org:acme:viewer' })).toBeNull(); + expect(knowledgeRoleOn(both, ['org:globex:viewer'], { address: 'org:acme' })).toBeNull(); }); it('matches literal segments exactly', () => { @@ -93,14 +117,21 @@ describe('binding params into patterns', () => { const account = compiled.declarations.get('account:$orgId:$accountId')!.pattern; it('encodes middle-segment colons without reaching another tenant', () => { - expect(compiled.match('org:a:b')!.params).toEqual({ orgId: 'a:b' }); + expect(compiled.match('org:a%3Ab')!.params).toEqual({ orgId: 'a:b' }); + expect(compiled.match('org:a:b')).toBeNull(); expect(knowledgePatternPrefix(team, { orgId: 'a:b' })).toBe('team:a%3Ab:'); expect(bindKnowledgePattern(team, { orgId: 'a:b', teamId: 'support' })).toBe('team:a%3Ab:support'); expect(knowledgePatternPrefix(team, { orgId: 'a' })).toBe('team:a:'); }); - it('preserves final colons and encodes reserved characters in every param', () => { - expect(bindKnowledgePattern(team, { orgId: 'a', teamId: 'b:c' })).toBe('team:a:b:c'); + it('encodes colons in every param, final ones included', () => { + expect(encodeKnowledgeScopeId('slack:U1/x#y%')).toBe('slack%3AU1%2Fx%23y%25'); + expect(decodeKnowledgeScopeId('slack%3AU1%2Fx%23y%25')).toBe('slack:U1/x#y%'); + expect(decodeKnowledgeScopeId('slack:U1')).toBeNull(); + expect(compiled.match(`org:${encodeKnowledgeScopeId('auth0|a:b')}`)?.params).toEqual({ orgId: 'auth0|a:b' }); + expect(bindKnowledgePattern(team, { orgId: 'a', teamId: 'b:c' })).toBe('team:a:b%3Ac'); + expect(knowledgeScopeAddress('resource:$resourceId', { resourceId: 'slack:U123' })).toBe('resource:slack%3AU123'); + expect(compiled.match('team:a:b%3Ac')?.params).toEqual({ orgId: 'a', teamId: 'b:c' }); expect(bindKnowledgePattern(team, { orgId: 'a', teamId: 'b/c' })).toBe('team:a:b%2Fc'); expect(knowledgePatternPrefix(account, { orgId: 'a/b' })).toBe('account:a%2Fb:'); }); @@ -110,19 +141,17 @@ describe('binding params into patterns', () => { expect(compiled.match('account:acme:1/foo')).toBeNull(); }); - it('round-trips Memory ids while keeping raw run scopes distinct from canonical addresses', () => { - const raw = ['resource:https://x/y#z', 'resource:a/b', 'resource:a%2Fb']; - expect(knowledgeRunScopes(compiled, raw)).toEqual([ - 'resource:https:%2F%2Fx%2Fy%23z', - 'resource:a%2Fb', - 'resource:a%252Fb', - ]); - expect(raw[0]).toBe('resource:https://x/y#z'); - expect(compiled.match('resource:https:%2F%2Fx%2Fy%23z')?.params).toEqual({ resourceId: 'https://x/y#z' }); + it('takes run scopes as canonical addresses, so each scope has one spelling', () => { + const encoded = `resource:${encodeKnowledgeScopeId('a/b:c')}`; + expect(encoded).toBe('resource:a%2Fb%3Ac'); + expect(knowledgeRunScopes(compiled, [encoded, encoded])).toEqual([encoded]); + for (const nonCanonical of ['resource:a/b', 'resource:a%2fb', 'resource:a%41', 'resource:a%']) + expect(() => knowledgeRunScopes(compiled, [nonCanonical])).toThrow(KnowledgeDeclarationError); + expect(compiled.match('resource:https%3A%2F%2Fx%2Fy%23z')?.params).toEqual({ resourceId: 'https://x/y#z' }); expect(knowledgeScopeAddress('resource:$resourceId', { resourceId: 'https://x/y#z' })).toBe( - 'resource:https:%2F%2Fx%2Fy%23z', + 'resource:https%3A%2F%2Fx%2Fy%23z', ); - expect(knowledgeRunScopes(compiled, [...raw])).toEqual(knowledgeRunScopes(compiled, raw)); + expect(() => knowledgeRunScopes(compiled, ['resource:https://x/y#z'])).toThrow(KnowledgeDeclarationError); }); it('keeps raw slash and hash out of canonical addresses, including types without children', () => { @@ -139,7 +168,7 @@ describe('binding params into patterns', () => { expect(knowledgeScopeAddress('team:$orgId:$teamId', { orgId: 'a:b', teamId: 'c/d#e%2F' })).toBe( 'team:a%3Ab:c%2Fd%23e%252F', ); - expect(knowledgeRunScopes(compiled, ['team:a:b:c'])).toEqual(['team:a:b:c']); + expect(() => knowledgeRunScopes(compiled, ['team:a:b:c'])).toThrow(KnowledgeDeclarationError); expect(() => knowledgeScopeAddress('team:$orgId:$teamId', { orgId: 'a', teamId: '' })).toThrow( KnowledgeDeclarationError, ); @@ -155,33 +184,37 @@ describe('compileKnowledgeScopes: validation', () => { expect(() => compileKnowledgeScopes({ 'lit:ab:$p': {} })).not.toThrow(); }); - it('accepts canonical escapes in concrete addresses and principals, and binds raw run scopes to them', () => { + it('accepts canonical escapes in concrete addresses, principals and run scopes', () => { const compiled = compileKnowledgeScopes({ ...knowledgeMemoryScopes(), 'resource:user%2F1': { access: [{ principal: 'org:a%2Fb', role: 'viewer' }] }, 'project:$projectId': {}, 'project:p1': { access: [{ principal: 'resource:user%2F1', role: 'editor' }] }, }); - const held = knowledgeRunScopes(compiled, ['resource:user/1']); + const held = knowledgeRunScopes(compiled, ['resource:user%2F1']); expect(held).toEqual(['resource:user%2F1']); expect(knowledgeRoleOn(compiled, held, { address: 'project:p1' })).toBe('editor'); - expect(knowledgeRoleOn(compiled, knowledgeRunScopes(compiled, ['org:a/b']), { address: 'resource:user%2F1' })).toBe( - 'viewer', - ); + expect( + knowledgeRoleOn(compiled, knowledgeRunScopes(compiled, ['org:a%2Fb']), { address: 'resource:user%2F1' }), + ).toBe('viewer'); expect(knowledgeRoleOn(compiled, ['resource:user%2F2'], { address: 'project:p1' })).toBeNull(); }); it('refuses overlapping patterns for one type', () => { - expect(() => compileKnowledgeScopes({ 'team:$orgId:$teamId': {}, 'team:$teamId': {} })).toThrow( + expect(() => compileKnowledgeScopes({ 'team:$orgId:$teamId': {}, 'team:$a:$b': {} })).toThrow( KnowledgeDeclarationError, ); }); - it('names both overlapping patterns, including final-parameter overlap with longer patterns', () => { + it('allows patterns of one type with different segment counts, since no value spans a colon', () => { + expect(() => compileKnowledgeScopes({ 'role:$orgId': {}, 'role:$orgId:admin': {} })).not.toThrow(); + expect(() => compileKnowledgeScopes({ 'team:$teamId': {}, 'team:$orgId:$teamId': {} })).not.toThrow(); + }); + + it('names both overlapping patterns', () => { for (const [left, right] of [ ['role:$orgId:$role', 'role:$orgId:admin'], ['kb:$orgId:$name', 'kb:$orgId:public'], - ['role:$orgId', 'role:$orgId:admin'], ]) { let error: unknown; try { diff --git a/packages/core/src/knowledge/__tests__/lazy-scopes.test.ts b/packages/core/src/knowledge/__tests__/lazy-scopes.test.ts index 458cd5d9fa9..0025f7795e1 100644 --- a/packages/core/src/knowledge/__tests__/lazy-scopes.test.ts +++ b/packages/core/src/knowledge/__tests__/lazy-scopes.test.ts @@ -39,6 +39,12 @@ describe('Knowledge scopes materialize on first write', () => { const { knowledge, call, context, scopes } = setup(); const held = ['org:acme', 'project:p1']; + expect(knowledge.__principalsKey(context(held, SLACK_USER)).split('\n')).toEqual([ + 'org:acme', + 'project:p1', + 'resource:slack%3AU123', + 'thread:slack%3AC1%3A1700000000.0001', + ]); await call(held, 'knowledge_search', { query: 'refund policy' }, SLACK_USER); await call(held, 'knowledge_list', {}, SLACK_USER); await expect(call(held, 'knowledge_read', { page: 'project:p1' }, SLACK_USER)).rejects.toThrow(/not found/); @@ -48,7 +54,7 @@ describe('Knowledge scopes materialize on first write', () => { await knowledge.__deliveredPins(context(held, SLACK_USER)); expect( - await scopes(['org:acme', 'project:p1', `resource:${SLACK_USER.resourceId}`, `thread:${SLACK_USER.threadId}`]), + await scopes(['org:acme', 'project:p1', 'resource:slack%3AU123', 'thread:slack%3AC1%3A1700000000.0001']), ).toEqual([]); }); diff --git a/packages/core/src/knowledge/__tests__/legacy-scope-rows.test.ts b/packages/core/src/knowledge/__tests__/legacy-scope-rows.test.ts new file mode 100644 index 00000000000..5bac804808d --- /dev/null +++ b/packages/core/src/knowledge/__tests__/legacy-scope-rows.test.ts @@ -0,0 +1,125 @@ +import { describe, expect, it } from 'vitest'; +import type { KnowledgeStorage } from '../../storage/domains/knowledge'; +import { InMemoryStore } from '../../storage/mock'; +import type { KnowledgeScopeDeclarations } from '../declarations'; +import { KnowledgeDeclarationError } from '../declarations'; +import { KnowledgeScopeRuntime } from '../scope-runtime'; + +const host = { author: 'host' }; + +// Before scope params matched exactly one segment, `org:acme:viewer` was an `org:$orgId` address +// (orgId "acme:viewer"), so scope rows like this one exist in stores written by older versions. +async function legacyStore() { + const store: KnowledgeStorage = (await new InMemoryStore().getStore('knowledge'))!; + await store.init(); + const { scope } = await store.materializeScope({ + address: 'org:acme:viewer', + declaration: 'org:$orgId', + name: 'org:acme:viewer', + provenance: host, + }); + await store.createPage({ parentId: scope.id, name: 'Legacy secret', provenance: host }); + return store; +} + +const SIDE_TYPE: KnowledgeScopeDeclarations = { + 'org:$orgId': { access: [{ principal: 'self', role: 'editor' }] }, + 'org:$orgId:viewer': { access: [{ principal: 'org:$orgId', role: 'viewer' }] }, +}; + +describe('Knowledge scope rows stored under a different declaration than their address now matches', () => { + it('grants nothing on them and keeps their pages out of reads', async () => { + const store = await legacyStore(); + const runtime = new KnowledgeScopeRuntime( + SIDE_TYPE, + async () => store, + () => {}, + ); + + const read = await runtime.readScopeFor(['org:acme']); + if (read === 'all') throw new Error('expected a narrowed read scope'); + expect(read.addresses).not.toContain('org:acme:viewer'); + const { pages } = await store.listPages({ read }); + expect(pages.map(page => page.name)).not.toContain('Legacy secret'); + + const [legacy] = await store.getScopesByAddress(['org:acme:viewer']); + expect(await runtime.roleOn(['org:acme'], legacy!)).toBeNull(); + expect((await runtime.explainAccess(['org:acme'], { scope: 'org:acme:viewer' })).role).toBeNull(); + }); + + it('refuses to adopt one as a scope of the new declaration', async () => { + const store = await legacyStore(); + const runtime = new KnowledgeScopeRuntime( + SIDE_TYPE, + async () => store, + () => {}, + ); + const error = await runtime.materializeScope('org:acme:viewer', ['org:acme'], host).catch(e => e); + expect(error).toBeInstanceOf(KnowledgeDeclarationError); + expect(error.message).toMatch(/"org:acme:viewer" was created from "org:\$orgId"/); + }); + + it('never resolves one as a belongsTo parent of the declaration that now matches it', async () => { + const store = await legacyStore(); + const runtime = new KnowledgeScopeRuntime( + { + ...SIDE_TYPE, + 'doc:$docId': { belongsTo: 'org:$orgId:viewer', access: [{ principal: 'org:$orgId', role: 'viewer' }] }, + }, + async () => store, + () => {}, + ); + const read = await runtime.readScopeFor(['org:acme']); + expect(read !== 'all' && read.children).toEqual([]); + }); + + it('never lets one give belongsTo roles to a child placed under it', async () => { + const store = await legacyStore(); + const [legacy] = await store.getScopesByAddress(['org:acme:viewer']); + const { scope: doc } = await store.materializeScope({ + address: 'doc:d1', + declaration: 'doc:$docId', + name: 'doc:d1', + parentId: legacy!.id, + provenance: host, + }); + const runtime = new KnowledgeScopeRuntime( + { + ...SIDE_TYPE, + 'doc:$docId': { belongsTo: 'org:$orgId:viewer', access: [{ principal: 'org:$orgId', role: 'editor' }] }, + }, + async () => store, + () => {}, + ); + expect(await runtime.roleOn(['org:acme'], doc)).toBeNull(); + expect((await runtime.explainAccess(['org:acme'], { scope: 'doc:d1' })).role).toBeNull(); + }); + + it('keeps reads its own declaration still grants by prefix, but no role', async () => { + // A prefix grant on org:$orgId covered this row when it was written; reads under that grant stay, + // as with any data written before the change. Nothing of org:$orgId:viewer reaches it. + const store = await legacyStore(); + const runtime = new KnowledgeScopeRuntime( + { + ...SIDE_TYPE, + 'agent:$agentId': {}, + 'org:$orgId': { + access: [ + { principal: 'self', role: 'editor' }, + { principal: 'agent:support', role: 'viewer' }, + ], + }, + 'org:$orgId:viewer': { access: [{ principal: 'agent:other', role: 'viewer' }] }, + }, + async () => store, + () => {}, + ); + const support = await runtime.readScopeFor(['agent:support']); + expect((await store.listPages({ read: support })).pages.map(page => page.name)).toContain('Legacy secret'); + const [legacy] = await store.getScopesByAddress(['org:acme:viewer']); + expect(await runtime.roleOn(['agent:support'], legacy!)).toBeNull(); + + const other = await runtime.readScopeFor(['agent:other']); + expect((await store.listPages({ read: other })).pages.map(page => page.name)).not.toContain('Legacy secret'); + }); +}); diff --git a/packages/core/src/knowledge/__tests__/memory-identity.test.ts b/packages/core/src/knowledge/__tests__/memory-identity.test.ts new file mode 100644 index 00000000000..97c0a772741 --- /dev/null +++ b/packages/core/src/knowledge/__tests__/memory-identity.test.ts @@ -0,0 +1,64 @@ +import { describe, expect, it } from 'vitest'; +import { setRunAgentScopes } from '../../agent/scopes'; +import { RequestContext } from '../../request-context'; +import { InMemoryStore } from '../../storage'; +import { knowledgeMemoryScopes } from '../declarations'; +import { Knowledge } from '../index'; +import { agentRunContext } from './agent-run-context'; + +// An Agent's `resource:`/`thread:` scopes are raw Memory ids (`resource:slack:U123` is user +// `slack:U123`). Knowledge binds the resolved ids encoded and takes identity from nowhere else. +function asAgent(storage: InMemoryStore, scopes: string[]) { + const knowledge = new Knowledge({ id: 'kb', storage, tools: true, scopes: knowledgeMemoryScopes() }); + const tools = knowledge.createTools(); + const context = agentRunContext('a', scopes); + return (tool: string, input: Record) => + tools[tool]!.execute!(input as never, context as never) as Promise; +} + +describe('Knowledge Memory identity from Agent scopes', () => { + it('binds a raw colon id encoded', async () => { + const call = asAgent(new InMemoryStore(), ['resource:slack:U123']); + const written = await call('knowledge_page', { op: 'write', scope: 'resource:slack%3AU123', name: 'Mine' }); + expect(written.page.id).toBeDefined(); + }); + + it("doesn't let a literal-percent id read the colon id's pages", async () => { + const storage = new InMemoryStore(); + const secret = await asAgent(storage, ['resource:slack:U123'])('knowledge_page', { + op: 'write', + scope: 'resource:slack%3AU123', + name: 'Secret', + body: 'COLON_ID_SECRET', + }); + + // User `slack%3AU123` (a literal percent) lives at resource:slack%253AU123. + const read = await asAgent(storage, ['resource:slack%3AU123'])('knowledge_read', { page: secret.page.id }).catch( + e => e, + ); + expect(JSON.stringify(read?.message ?? read)).not.toContain('COLON_ID_SECRET'); + }); + + it('ignores resource:/thread: strings written into the run scopes directly', async () => { + // Core strips identity scopes before marking a run's scopes, so this only happens when code + // marks them itself. They still mustn't act as a second, canonical identity. + const storage = new InMemoryStore(); + const secret = await asAgent(storage, ['resource:slack:U123'])('knowledge_page', { + op: 'write', + scope: 'resource:slack%3AU123', + name: 'Secret', + body: 'COLON_ID_SECRET', + }); + const knowledge = new Knowledge({ id: 'kb', storage, tools: true, scopes: knowledgeMemoryScopes() }); + const requestContext = new RequestContext(); + setRunAgentScopes(requestContext, ['resource:slack%3AU123']); + const read = await knowledge.createTools().knowledge_read!.execute!( + { page: secret.page.id } as never, + { + requestContext, + agent: { agentId: 'a', resourceId: 'slack%3AU123' }, + } as never, + ).catch(e => e); + expect(JSON.stringify((read as any)?.message ?? read)).not.toContain('COLON_ID_SECRET'); + }); +}); diff --git a/packages/core/src/knowledge/__tests__/page-tools.test.ts b/packages/core/src/knowledge/__tests__/page-tools.test.ts index 3aed3064ac8..9eaa4c01acd 100644 --- a/packages/core/src/knowledge/__tests__/page-tools.test.ts +++ b/packages/core/src/knowledge/__tests__/page-tools.test.ts @@ -1,6 +1,4 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'; -import { setRunAgentScopes } from '../../agent/scopes'; -import { RequestContext } from '../../request-context'; import { standardSchemaToJSONSchema } from '../../schema'; import type { KnowledgeStorage } from '../../storage/domains/knowledge'; import { InMemoryStore } from '../../storage/mock'; @@ -10,6 +8,7 @@ import type { KnowledgeScopeDeclarations } from '../declarations'; import { KNOWLEDGE_WRITE_INSTRUCTIONS } from '../instructions'; import { buildKnowledgePageTools } from '../page-tools'; import { KnowledgeScopeRuntime } from '../scope-runtime'; +import { agentRunContext } from './agent-run-context'; /** The §10 reference setup of the access spec. */ const scopes: KnowledgeScopeDeclarations = { @@ -71,12 +70,10 @@ describe('Knowledge page tools (spec §10 scenarios, in-memory store)', () => { let tools: ReturnType; let runtime: KnowledgeScopeRuntime; - /** Runs a tool as an agent holding `held` (raw run scopes). */ + /** Runs a tool as an agent run with `held` as its Agent scopes. */ const as = (agentId: string, held: string[]) => { const call = async (tool: string, input: Record): Promise => { - const requestContext = new RequestContext(); - setRunAgentScopes(requestContext, held); - return (await tools[tool]!.execute!(input as never, { requestContext, agent: { agentId } } as never)) as Result; + return (await tools[tool]!.execute!(input as never, agentRunContext(agentId, held) as never)) as Result; }; return { call, @@ -579,15 +576,18 @@ describe('Knowledge page tools (spec §10 scenarios, in-memory store)', () => { }); }); - it("refuses a typo'd run scope the way a run does, and takes raw run scopes", async () => { + it("refuses a typo'd run scope the way a run does, and takes canonical run scopes", async () => { await expect(runtime.explainAccess(['org:acme', 'role:acme:suport'], { scope: 'org:acme' })).rejects.toThrow( KnowledgeDeclarationError, ); await expect(as('typo', ['org:acme', 'role:acme:suport']).read()).rejects.toThrow(/role:acme:suport/); - // A raw resource id with "/" is encoded exactly like run ingress encodes it. - const raw = await runtime.explainAccess(['resource:user/1'], { scope: 'resource:user%2F1' }); - expect(raw.role).toBe('owner'); + // Run scopes are canonical: an id with "/" is passed encoded, and the raw spelling is refused. + const encoded = await runtime.explainAccess(['resource:user%2F1'], { scope: 'resource:user%2F1' }); + expect(encoded.role).toBe('owner'); + await expect(runtime.explainAccess(['resource:user/1'], { scope: 'resource:user%2F1' })).rejects.toThrow( + /encodeKnowledgeScopeId/, + ); }); }); }); diff --git a/packages/core/src/knowledge/__tests__/semantic.test.ts b/packages/core/src/knowledge/__tests__/semantic.test.ts index 8df64f3aeb2..0d6c7fb3d53 100644 --- a/packages/core/src/knowledge/__tests__/semantic.test.ts +++ b/packages/core/src/knowledge/__tests__/semantic.test.ts @@ -1,8 +1,6 @@ import { APICallError } from '@internal/ai-sdk-v5'; import { estimateTokenCount } from 'tokenx'; import { afterEach, beforeEach, describe, expect, it } from 'vitest'; -import { setRunAgentScopes } from '../../agent/scopes'; -import { RequestContext } from '../../request-context'; import type { KnowledgeStorage } from '../../storage/domains/knowledge'; import { InMemoryStore } from '../../storage/mock'; import { MastraVector } from '../../vector'; @@ -22,6 +20,7 @@ import type { import { knowledgeMemoryScopes } from '../declarations'; import { Knowledge } from '../index'; import { KnowledgeSemanticIndex } from '../semantic'; +import { agentRunContext } from './agent-run-context'; /** A real exact-cosine vector store held in memory; records every topK it is asked for. */ class MemoryVector extends MastraVector { @@ -162,12 +161,7 @@ describe('Knowledge semantic search', () => { const as = (held: string[]) => { const tools = knowledge.createTools(); return async (tool: string, input: Record): Promise => { - const requestContext = new RequestContext(); - setRunAgentScopes(requestContext, held); - return (await tools[tool]!.execute!( - input as never, - { requestContext, agent: { agentId: 'a' } } as never, - )) as Result; + return (await tools[tool]!.execute!(input as never, agentRunContext('a', held) as never)) as Result; }; }; const acme = () => as(['org:acme', 'resource:u-acme']); diff --git a/packages/core/src/knowledge/declarations.ts b/packages/core/src/knowledge/declarations.ts index 95f1df0df26..a9a32ad508a 100644 --- a/packages/core/src/knowledge/declarations.ts +++ b/packages/core/src/knowledge/declarations.ts @@ -243,8 +243,8 @@ function parsePattern(key: string, what: string): KnowledgeScopePattern { if (new Set(params).size !== params.length) { throw new KnowledgeDeclarationError(`${what} "${key}" repeats a param.`); } - // A pattern's literals match raw run scopes as written, so an escape in one would let a raw scope - // pass for a different decoded value. Concrete addresses and principals are canonical: `%` there is an escape. + // Literals are compared as written while param values are decoded, so a `%` in a literal would be + // ambiguous. Concrete addresses and principals are canonical: `%` there is an escape. if (params.length > 0 && segments.some(segment => 'literal' in segment && segment.literal.includes('%'))) { throw new KnowledgeDeclarationError( `${what} "${key}" has a literal containing "%"; only params take encoded values.`, @@ -255,25 +255,26 @@ function parsePattern(key: string, what: string): KnowledgeScopePattern { /** Binds raw param values from a canonical address; null when it isn't canonical or doesn't fit. */ export function matchKnowledgePattern(pattern: KnowledgeScopePattern, address: string): Record | null { - return matchPattern(pattern, address, false); + return matchPattern(pattern, address); } -function matchPattern(pattern: KnowledgeScopePattern, address: string, raw: boolean): Record | null { +function matchPattern(pattern: KnowledgeScopePattern, address: string): Record | null { const prefix = `${pattern.type}:`; if (!address.startsWith(prefix)) return null; const parts = address.slice(prefix.length).split(':'); + // One segment per param, never more: a value can't hold a raw colon, so `org:x:viewer` is not an + // `org:$orgId` address (it would otherwise be `self` there). Colons in ids are encoded as %3A. + if (parts.length !== pattern.segments.length) return null; const params: Record = {}; for (let i = 0; i < pattern.segments.length; i++) { const segment = pattern.segments[i]!; - const last = i === pattern.segments.length - 1; if ('literal' in segment) { if (parts[i] !== segment.literal) return null; - if (last && parts.length !== pattern.segments.length) return null; continue; } - const value = last ? parts.slice(i).join(':') : parts[i]; + const value = parts[i]; if (!value) return null; - const decoded = raw ? value : decodeKnowledgeScopeValue(value, last); + const decoded = decodeKnowledgeScopeValue(value); if (decoded === null) return null; params[segment.param] = decoded; } @@ -281,8 +282,7 @@ function matchPattern(pattern: KnowledgeScopePattern, address: string, raw: bool } /** - * A canonical address from raw param values. For Knowledge APIs, templates, pins and tools only: - * NOT for Agent scopes, which always take raw addresses and treat every percent sign literally. + * A canonical address from raw param values, the form Knowledge APIs, pins, tools and Agent scopes take. * @experimental */ export function knowledgeScopeAddress(pattern: string, params: Record): string { @@ -292,18 +292,20 @@ export function knowledgeScopeAddress(pattern: string, params: Record { for (const declaration of compiled.declarations.values()) { if (declaration.child) continue; - const params = matchPattern(declaration.pattern, scope, true); - if (params) return bindKnowledgePattern(declaration.pattern, params)!; + if (matchPattern(declaration.pattern, scope)) return scope; } throw new KnowledgeDeclarationError( - `Knowledge run scope "${scope}" does not match a declared scope type. Declare it in Knowledge \`scopes\` (for Memory's resource:/thread: scopes, spread \`...knowledgeMemoryScopes()\`).`, + `Knowledge run scope "${scope}" does not match a declared scope type. Declare it in Knowledge \`scopes\` (for Memory's resource:/thread: scopes, spread \`...knowledgeMemoryScopes()\`), and encode ids containing ":", "/", "#" or "%" with encodeKnowledgeScopeId.`, ); }), ), @@ -320,7 +322,7 @@ export function bindKnowledgePattern(pattern: KnowledgeScopePattern, params: Rec } const value = params[segment.param]; if (value === undefined || value === '') return null; - values.push(encodeKnowledgeScopeValue(value, i === pattern.segments.length - 1)); + values.push(encodeKnowledgeScopeValue(value)); } return `${pattern.type}:${values.join(':')}`; } @@ -340,7 +342,7 @@ export function knowledgePatternPrefix(pattern: KnowledgeScopePattern, params: R const value = params[segment.param]; if (value === undefined) break; if (value === '') return null; - prefix += `${encodeKnowledgeScopeValue(value, false)}:`; + prefix += `${encodeKnowledgeScopeValue(value)}:`; } return prefix; } @@ -357,9 +359,7 @@ function patternsOverlap(a: KnowledgeScopePattern, b: KnowledgeScopePattern): bo const right = b.segments[i]!; if ('literal' in left && 'literal' in right && left.literal !== right.literal) return false; } - if (a.segments.length === b.segments.length) return true; - const shorter = a.segments.length < b.segments.length ? a : b; - return 'param' in shorter.segments[shorter.segments.length - 1]!; + return a.segments.length === b.segments.length; } /** diff --git a/packages/core/src/knowledge/index.ts b/packages/core/src/knowledge/index.ts index 75e0d1b6583..7af3d36fc45 100644 --- a/packages/core/src/knowledge/index.ts +++ b/packages/core/src/knowledge/index.ts @@ -150,7 +150,7 @@ export class Knowledge extends MastraBase { /** * Why a run holding `runScopes` can or can't reach a scope or page: its role there and the rules - * that give it. `runScopes` are raw run scopes, as passed to an agent run; undeclared ones throw + * that give it. `runScopes` are canonical run scopes, as passed to an agent run; undeclared ones throw * like they do at run start. `target` is a scope address, or a page id or `#[/…]`. * * **Host-only.** It tells a missing page from a hidden one, which runs must never learn. Never @@ -490,6 +490,7 @@ export type { } from './explorer-pages'; export type { KnowledgeConfig } from './config'; export { knowledgeScopeAddress, knowledgeMemoryScopes, KnowledgeDeclarationError } from './declarations'; +export { decodeKnowledgeScopeId, encodeKnowledgeScopeId } from './scope-address'; export type { KnowledgePageTemplate, KnowledgePinnedList, diff --git a/packages/core/src/knowledge/run.ts b/packages/core/src/knowledge/run.ts index 49031efe16c..ef85fcff6c9 100644 --- a/packages/core/src/knowledge/run.ts +++ b/packages/core/src/knowledge/run.ts @@ -1,4 +1,4 @@ -import { getRunAgentScopes } from '../agent/scopes'; +import { getRunAgentScopes, withoutIdentityAgentScopes } from '../agent/scopes'; import type { KnowledgePage, KnowledgeProvenance, @@ -7,7 +7,12 @@ import type { } from '../storage/domains/knowledge'; import { knowledgeScopeReadable, parseKnowledgePageRef } from '../storage/domains/knowledge'; import { knowledgeRoleOn } from './access'; -import { knowledgeRoleAtLeast, knowledgeRunScopes } from './declarations'; +import { + KnowledgeDeclarationError, + knowledgeRoleAtLeast, + knowledgeRunScopes, + knowledgeScopeAddress, +} from './declarations'; import type { KnowledgeRole } from './declarations'; import { knowledgePageRefs } from './page-refs'; import type { KnowledgeScopeRuntime } from './scope-runtime'; @@ -204,11 +209,25 @@ export function knowledgeRunPrincipals( runtime: KnowledgeScopeRuntime, context: KnowledgeRunContext | undefined, ): string[] { - const raw = getRunAgentScopes(context?.requestContext); - if (context?.agent?.resourceId) raw.push(`resource:${context.agent.resourceId}`); - if (context?.agent?.threadId) raw.push(`thread:${context.agent.threadId}`); - if (raw.length === 0) { + // Identity comes only from the resolved Memory ids below. Core already strips resource:/thread: from + // the run's scopes; one written there anyway is raw Memory syntax, not a canonical address. + const raw = withoutIdentityAgentScopes(getRunAgentScopes(context?.requestContext)); + // Memory ids are app-chosen and may contain colons (`slack:U123`), so they're bound encoded rather + // than parsed back out of a raw `resource:` string. + const memory: string[] = []; + if (context?.agent?.resourceId) + memory.push(knowledgeScopeAddress('resource:$resourceId', { resourceId: context.agent.resourceId })); + if (context?.agent?.threadId) + memory.push(knowledgeScopeAddress('thread:$threadId', { threadId: context.agent.threadId })); + if (raw.length === 0 && memory.length === 0) { throw new Error('Knowledge tools need run scopes: give the agent or the call `scopes`, or run it with Memory.'); } - return knowledgeRunScopes(runtime.compiled, raw); + for (const address of memory) { + if (!runtime.compiled.match(address)) { + throw new KnowledgeDeclarationError( + `Knowledge run scope "${address}" does not match a declared scope type. Declare it in Knowledge \`scopes\` (for Memory's resource:/thread: scopes, spread \`...knowledgeMemoryScopes()\`).`, + ); + } + } + return [...new Set([...knowledgeRunScopes(runtime.compiled, raw), ...memory])]; } diff --git a/packages/core/src/knowledge/scope-address.ts b/packages/core/src/knowledge/scope-address.ts index 9458e738781..161306ed0cc 100644 --- a/packages/core/src/knowledge/scope-address.ts +++ b/packages/core/src/knowledge/scope-address.ts @@ -1,10 +1,9 @@ /** Reserved characters are escaped once at the raw-id boundary; Knowledge addresses stay canonical. */ -export function encodeKnowledgeScopeValue(value: string, final: boolean): string { - const encoded = value.replaceAll('%', '%25').replaceAll('/', '%2F').replaceAll('#', '%23'); - return final ? encoded : encoded.replaceAll(':', '%3A'); +export function encodeKnowledgeScopeValue(value: string): string { + return value.replaceAll('%', '%25').replaceAll('/', '%2F').replaceAll('#', '%23').replaceAll(':', '%3A'); } -export function decodeKnowledgeScopeValue(value: string, final: boolean): string | null { +export function decodeKnowledgeScopeValue(value: string): string | null { const decoded = value.replace(/%(25|2F|23|3A)/g, (_, code: string) => { switch (code) { case '25': @@ -17,5 +16,24 @@ export function decodeKnowledgeScopeValue(value: string, final: boolean): string return ':'; } }); - return encodeKnowledgeScopeValue(decoded, final) === value ? decoded : null; + return encodeKnowledgeScopeValue(decoded) === value ? decoded : null; +} + +/** + * Encodes an id (a tenant, user or resource id) for one segment of a canonical Knowledge scope + * address, e.g. `org:${encodeKnowledgeScopeId('auth0|a:b')}`. `:`, `/`, `#` and `%` are escaped, so + * the id can't spill into another segment, a child scope or a page ref. + * @experimental + */ +export function encodeKnowledgeScopeId(id: string): string { + return encodeKnowledgeScopeValue(id); +} + +/** + * The id back from one segment of a canonical Knowledge scope address; null when the segment isn't + * canonically encoded. + * @experimental + */ +export function decodeKnowledgeScopeId(segment: string): string | null { + return decodeKnowledgeScopeValue(segment); } diff --git a/packages/core/src/knowledge/scope-runtime.ts b/packages/core/src/knowledge/scope-runtime.ts index ee30f1f6af4..91455a73fd3 100644 --- a/packages/core/src/knowledge/scope-runtime.ts +++ b/packages/core/src/knowledge/scope-runtime.ts @@ -119,19 +119,57 @@ export class KnowledgeScopeRuntime { return renamed; } + /** + * Whether a stored scope row belongs to the declaration its address matches today. Rows written + * before scope params matched exactly one segment can carry another (`org:acme:viewer` stored + * under `org:$orgId`); they must not pick up the rules of the declaration that now matches them. + */ + #isCurrent(scope: KnowledgePage): boolean { + return !scope.declaration || this.compiled.match(scope.address!)?.declaration === scope.declaration; + } + + #assertCurrent(scope: KnowledgePage): void { + if (this.#isCurrent(scope)) return; + throw new KnowledgeDeclarationError( + `Knowledge scope "${scope.address}" was created from "${scope.declaration}", which no longer matches it ` + + `(scope params match one segment; encode colons in ids as %3A). It can't be used as a scope of ` + + `"${this.compiled.match(scope.address!)?.declaration}".`, + ); + } + async readScopeFor(principals: readonly string[]): Promise { this.validatePrincipals(principals); await this.checkDeclarations(); const storage = await this.getStorage(); - return knowledgeReadScopeFor(this.compiled, principals, addresses => storage.getScopesByAddress(addresses)); + // belongsTo parents resolve through current rows only, so a stale row can't parent new children. + const read = await knowledgeReadScopeFor(this.compiled, principals, async addresses => + (await storage.getScopesByAddress(addresses)).filter(scope => this.#isCurrent(scope)), + ); + if (read === 'all' || read.addresses.length === 0) return read; + const stale = new Set( + (await storage.getScopesByAddress(read.addresses)) + .filter(scope => !this.#isCurrent(scope)) + .map(scope => scope.address!), + ); + return stale.size ? { ...read, addresses: read.addresses.filter(address => !stale.has(address)) } : read; } async roleOn(principals: readonly string[], scope: KnowledgePage): Promise { this.validatePrincipals(principals); if (!scope.isScope || !scope.address) throw new Error('Knowledge roles require a scope page.'); + if (!this.#isCurrent(scope)) return null; const storage = await this.getStorage(); - const parent = scope.parentId ? await storage.getPage({ id: scope.parentId, read: 'all' }) : null; - return knowledgeRoleOn(this.compiled, principals, { address: scope.address, parentAddress: parent?.address }); + return knowledgeRoleOn(this.compiled, principals, { + address: scope.address, + parentAddress: await this.#currentParentAddress(storage, scope), + }); + } + + // A stale parent row (its address now matches another declaration) must not bind belongsTo rules. + async #currentParentAddress(storage: KnowledgeStorage, scope: KnowledgePage): Promise { + if (!scope.parentId) return undefined; + const parent = await storage.getPage({ id: scope.parentId, read: 'all' }); + return parent && this.#isCurrent(parent) ? (parent.address ?? undefined) : undefined; } async explainAccess( @@ -168,8 +206,13 @@ export class KnowledgeScopeRuntime { } const address = scope?.address ?? (target as { scope: string }).scope; - const parent = scope?.parentId ? await storage.getPage({ id: scope.parentId, read: 'all' }) : null; - const reasons = knowledgeAccessGrants(this.compiled, principals, { address, parentAddress: parent?.address }); + const reasons = + scope && !this.#isCurrent(scope) + ? [] + : knowledgeAccessGrants(this.compiled, principals, { + address, + parentAddress: scope ? await this.#currentParentAddress(storage, scope) : undefined, + }); let role: KnowledgeRole | null = null; for (const reason of reasons) role = strongerKnowledgeRole(role, reason.role); return { @@ -294,6 +337,7 @@ export class KnowledgeScopeRuntime { } const existing = await lookUp(address); + if (existing) this.#assertCurrent(existing); let parentId = existing?.parentId; const belongsTo = match.compiled.belongsTo; if (belongsTo) { @@ -349,6 +393,7 @@ export class KnowledgeScopeRuntime { pages: declaration.pages, provenance, }); + this.#assertCurrent(result.scope); if (result.created) { // A new scope (and its config pages) can resolve body links written before it existed. await updateKnowledgeLinks(this.warn, () => From 338ec039256b5babdff8c079671fb87b02db08f5 Mon Sep 17 00:00:00 2001 From: "mastra-platform[bot]" <284800079+mastra-platform[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 18:44:49 -0500 Subject: [PATCH 007/239] fix(factory-ui): align finished onboarding step's checkmark with step numbers (#30248) > Opened by @roaminro ## Summary On the Factory "Set up your factory" page, the checkmark on a finished step (e.g. Codebase) sat 12px to the right of the numbers on the open and upcoming steps. The cause was `before:transition-none` on the finished row's button. In Tailwind v4, any `before:` utility gives the element a `::before` box (`content: var(--tw-content)`, which resolves to `""`). The button is a `flex gap-3` row, so that empty box became its first item and added one 12px gap before the checkmark. `state-layer` now paints the hover background on the button itself rather than a `::before`, so the class did nothing useful. This PR removes it. I checked the other `before:` classes in factory-ui. They're either skeleton shimmers that need the pseudo-element, or absolutely positioned drop indicators, so none of them affect layout. ## Test plan - [x] Verified in the browser on the latest release: the button's computed padding is 16px, but the checkmark sits 28px from the card edge, while the open and upcoming steps' numbers sit at 16px. `getComputedStyle(button, '::before').content` returns `""`, which means the `::before` box exists. - [x] Removing the class in the browser moves the checkmark into line with the step numbers (confirmed by @roaminro). Co-authored-by: mastra-platform[bot] Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/factory-onboarding-check-align.md | 5 +++++ .../workspaces/components/onboarding/OnboardingStepRow.tsx | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 .changeset/factory-onboarding-check-align.md diff --git a/.changeset/factory-onboarding-check-align.md b/.changeset/factory-onboarding-check-align.md new file mode 100644 index 00000000000..7f023695c77 --- /dev/null +++ b/.changeset/factory-onboarding-check-align.md @@ -0,0 +1,5 @@ +--- +'mastra': patch +--- + +Fixed the checkmark on a finished Factory onboarding step sitting 12px right of the step numbers below it. diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/components/onboarding/OnboardingStepRow.tsx b/mastracode/factory-ui/src/ui/domains/workspaces/components/onboarding/OnboardingStepRow.tsx index 40d952fa5af..a7faaafa095 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/components/onboarding/OnboardingStepRow.tsx +++ b/mastracode/factory-ui/src/ui/domains/workspaces/components/onboarding/OnboardingStepRow.tsx @@ -67,7 +67,7 @@ export function OnboardingDoneRow({ disabled={changeDisabled} onClick={onChange} className={cn( - 'state-layer flex min-h-14 w-full cursor-pointer items-center gap-3 px-4 py-3 text-start before:transition-none disabled:cursor-not-allowed', + 'state-layer flex min-h-14 w-full cursor-pointer items-center gap-3 px-4 py-3 text-start disabled:cursor-not-allowed', ONBOARDING_FRAME_RADIUS, focusRingInset, )} From 461b3886c13c3054e66a24d170778d901e335a92 Mon Sep 17 00:00:00 2001 From: Abhi Aiyer Date: Thu, 12 Nov 2026 15:50:17 -0800 Subject: [PATCH 008/239] feat(factory): keep intake integrations off until enabled (#30251) ## Summary Connecting an intake integration used to start pulling its items onto boards right away, because an org with no saved intake config was treated as having every integration enabled. Unset config now resolves to disabled, both on the server and in the board intake UI, so nothing is ingested until the org turns the integration on in intake settings. ## Test plan - [x] `tsc --noEmit` for `mastracode/factory` and `mastracode/factory-ui` - [x] `vitest run` intake routes, intake storage, Jira/Linear intake routes (updated the default-config expectations: `/web/intake/config` now reports disabled, and Jira issues return `jira_intake_disabled` with no saved config) ELI5: Connected intake integrations used to start adding items to boards right away. Now they stay off until an organization turns them on in intake settings. ## Summary This PR changes the default intake state for integrations with no saved configuration from enabled to disabled. The change applies on the server and in the board intake UI. Connected integrations no longer ingest items onto boards until an organization enables them. ## Changes - **Changeset** (`.changeset/plenty-nails-slide.md`): Adds a minor release note for `@mastra/factory`. It states that intake integrations stay off until enabled in intake settings. - **Storage defaults** (`mastracode/factory/src/storage/domains/intake/base.ts`): - `IntakeStorage.getConfig` returns `{ enabled: false, sourceIds: null }` for requested integration ids that have no saved entry. The doc comment is updated to match. - The selection update path in `migrateSourceIds` uses `{ enabled: false }` as the base when an integration entry is absent. It still sets `sourceIds` from the selection. - **UI default** (`mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardIntake.ts`): `githubEnabled` falls back to `false` when `config?.github.enabled` is undefined. The previous fallback was `true`. - **Tests**: - `routes/intake.test.ts`: The default configuration test now expects `github` and `linear` with `enabled: false` and `sourceIds: null`. - `integrations/platform/jira/routes.test.ts`: For an organization with no saved intake config, the issues route test now expects HTTP 404 with `error: 'jira_intake_disabled'`. It replaces the prior expectation of HTTP 200 with an empty page. The test still asserts that `listActiveJiraIssues` is not called. ## Not verified - Test and type-check results were not run in this review. The PR lists `tsc --noEmit` and `vitest run` as its test plan, but no completed check results were available. Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/plenty-nails-slide.md | 5 +++++ .../src/ui/domains/factory/hooks/useBoardIntake.ts | 2 +- .../factory/src/integrations/platform/jira/routes.test.ts | 6 +++--- mastracode/factory/src/routes/intake.test.ts | 6 +++--- mastracode/factory/src/storage/domains/intake/base.ts | 6 +++--- 5 files changed, 15 insertions(+), 10 deletions(-) create mode 100644 .changeset/plenty-nails-slide.md diff --git a/.changeset/plenty-nails-slide.md b/.changeset/plenty-nails-slide.md new file mode 100644 index 00000000000..4e4f289d753 --- /dev/null +++ b/.changeset/plenty-nails-slide.md @@ -0,0 +1,5 @@ +--- +'@mastra/factory': minor +--- + +Intake integrations are now off until you turn them on. A newly connected integration no longer starts pulling items onto your boards until you enable it in the intake settings. diff --git a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardIntake.ts b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardIntake.ts index 9ea8732a891..bcf6897936e 100644 --- a/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardIntake.ts +++ b/mastracode/factory-ui/src/ui/domains/factory/hooks/useBoardIntake.ts @@ -186,7 +186,7 @@ export function useBoardIntake({ const config = configQuery.data; const gitlabStatusQuery = useGitLabStatusQuery(true); - const githubEnabled = config?.github.enabled ?? true; + const githubEnabled = config?.github.enabled ?? false; // Every linked GitHub repository feeds intake, not just the first one. Pull requests come from // all of them; issues only from the repositories selected as issue sources. const reviewRepositoryIds = repositories diff --git a/mastracode/factory/src/integrations/platform/jira/routes.test.ts b/mastracode/factory/src/integrations/platform/jira/routes.test.ts index 2eb21c16be3..1695b0bd530 100644 --- a/mastracode/factory/src/integrations/platform/jira/routes.test.ts +++ b/mastracode/factory/src/integrations/platform/jira/routes.test.ts @@ -269,13 +269,13 @@ describe('issues route', () => { expect(listActiveJiraIssues).not.toHaveBeenCalled(); }); - it('returns an empty page when there is no saved intake config', async () => { + it('treats an org with no saved intake config as Jira intake turned off', async () => { seed = await createFactoryStorageForTests(); const res = await buildApp(org1()).request('/web/jira/issues'); - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ issues: [], nextCursor: null }); + expect(res.status).toBe(404); + expect(await res.json()).toMatchObject({ error: 'jira_intake_disabled' }); expect(listActiveJiraIssues).not.toHaveBeenCalled(); }); diff --git a/mastracode/factory/src/routes/intake.test.ts b/mastracode/factory/src/routes/intake.test.ts index 621d47ea7c6..a145444e007 100644 --- a/mastracode/factory/src/routes/intake.test.ts +++ b/mastracode/factory/src/routes/intake.test.ts @@ -88,12 +88,12 @@ describe('intake configuration', () => { expect((await buildApp({ workosId: 'u1' }).request('/web/intake/config')).status).toBe(403); }); - it('defaults every configured capability to enabled with no selected sources', async () => { + it('defaults every configured capability to disabled with no selected sources', async () => { const response = await buildApp(orgUser).request('/web/intake/config'); expect(await response.json()).toEqual({ config: { - github: { enabled: true, sourceIds: null }, - linear: { enabled: true, sourceIds: null }, + github: { enabled: false, sourceIds: null }, + linear: { enabled: false, sourceIds: null }, }, }); }); diff --git a/mastracode/factory/src/storage/domains/intake/base.ts b/mastracode/factory/src/storage/domains/intake/base.ts index 4bcc14722ac..df6f7e5773d 100644 --- a/mastracode/factory/src/storage/domains/intake/base.ts +++ b/mastracode/factory/src/storage/domains/intake/base.ts @@ -412,7 +412,7 @@ export class IntakeStorage extends FactoryStorageDomain { orgId: string; /** * When provided, the result contains exactly these integration ids, with - * unset integrations defaulting to `{ enabled: true, sourceIds: null }`. + * unset integrations defaulting to `{ enabled: false, sourceIds: null }`. */ integrationIds?: string[]; }): Promise { @@ -420,7 +420,7 @@ export class IntakeStorage extends FactoryStorageDomain { const saved = structuredClone(row?.config ?? DEFAULT_INTAKE_CONFIG); if (!integrationIds) return saved; return Object.fromEntries( - integrationIds.map(integrationId => [integrationId, saved[integrationId] ?? { enabled: true, sourceIds: null }]), + integrationIds.map(integrationId => [integrationId, saved[integrationId] ?? { enabled: false, sourceIds: null }]), ); } @@ -697,7 +697,7 @@ export class IntakeStorage extends FactoryStorageDomain { ) { const config = structuredClone(configRow.config); config[integrationId] = { - ...(config[integrationId] ?? { enabled: true }), + ...(config[integrationId] ?? { enabled: false }), sourceIds: nextSelected.length > 0 ? nextSelected : null, }; await ops.updateMany('intake_org_settings', { org_id: orgId }, { config, updated_at: now }); From ab1968631a6129288ebc300c3f3f11313da36ae6 Mon Sep 17 00:00:00 2001 From: "mastra-platform[bot]" <284800079+mastra-platform[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:52:51 +0000 Subject: [PATCH 009/239] fix(create-factory): default project region to US instead of prompting (#30249) > Opened by @DSchau ## Summary `create-factory` used to stop during platform setup and ask "Where should your Factory project run?" (us/eu). Most people can't answer that during first-time setup, and it blocks agents that run the installer for you. This removes the prompt. Projects are created in `us` by default, along with the matching Neon database region (`aws-us-west-2`). EU users can still opt in with the existing `--region eu` flag. That flag is now described in `--help` ("defaults to us") and in the README. ## Changes - `src/create.ts`: dropped the region `select` prompt. The region is now `region ?? 'us'`. - `src/index.ts`: updated the `--region` help text. - `README.md`: documented `--region eu`. - Tests: the default flow now creates the project in `us` without prompting, and `--region eu` reaches project creation, the production environment and the Neon region. - Changeset (patch). ## Test plan - `npx vitest run`: 58/58 pass - `npx tsc --noEmit`, `oxlint --type-aware`: clean Companion docs PR in `mastra-ai/softwarefactory-docs` updates the `create-factory` reference page. ELI5: Before this change, the Factory setup tool asked users which region to use for their project. Now it uses the US region by default. People who need the EU region can still pass `--region eu`. ## Summary This pull request removes the region prompt from `create-factory` during platform provisioning. The tool now selects a region without asking the user. ### Behavior changes - `runPlatformProvisioning` in `mastracode/mastra-factory/src/create.ts` no longer shows a `p.select` region picker. It sets `projectRegion = region ?? 'us'`. The supplied `--region` value wins when present. - The selected region drives project creation, production-environment setup, and the Neon region lookup. The US default maps to `aws-us-west-2`. The EU value maps to `aws-eu-central-1`. - The `PROJECT_REGION_OPTIONS` constant and its prompt-cancel handling are removed. - The `--region` help text in `mastracode/mastra-factory/src/index.ts` changes from "prompts when omitted" to "defaults to `us`". ### Documentation - `mastracode/mastra-factory/README.md` documents that platform projects default to the US region. It also shows how to pass `--region eu`. - `.changeset/quiet-regions-default.md` adds a `patch` changeset for `create-factory`. It describes the new default and the `--region eu` option. ### Tests - `mastracode/mastra-factory/src/create.test.ts` no longer simulates region selection. - Default provisioning expectations use `us` and `aws-us-west-2`. - The explicit-region test uses `eu` and `aws-eu-central-1`. - The tests assert that the default path does not prompt. ### Diff size - 5 files changed, 27 lines added, 33 lines removed. ### Verification status - The diff confirms the source changes listed above. - The author reports `npx vitest run` (58/58), `npx tsc --noEmit`, and `oxlint --type-aware` as passing. These checks were not run as part of this review, so their results are not confirmed here. --------- Co-authored-by: mastra-platform[bot] Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/quiet-regions-default.md | 9 +++++++ mastracode/mastra-factory/README.md | 6 +++++ mastracode/mastra-factory/src/create.test.ts | 26 ++++++++------------ mastracode/mastra-factory/src/create.ts | 17 +------------ mastracode/mastra-factory/src/index.ts | 2 +- 5 files changed, 27 insertions(+), 33 deletions(-) create mode 100644 .changeset/quiet-regions-default.md diff --git a/.changeset/quiet-regions-default.md b/.changeset/quiet-regions-default.md new file mode 100644 index 00000000000..b0d01424526 --- /dev/null +++ b/.changeset/quiet-regions-default.md @@ -0,0 +1,9 @@ +--- +'create-factory': patch +--- + +`create-factory` no longer asks where your Factory project should run. New projects are created in the US region by default. To create the project in the EU instead, pass `--region eu`: + +```bash +npx create-factory@latest my-mastra-factory --region eu +``` diff --git a/mastracode/mastra-factory/README.md b/mastracode/mastra-factory/README.md index 7c913c35d8d..8d101a7b758 100644 --- a/mastracode/mastra-factory/README.md +++ b/mastracode/mastra-factory/README.md @@ -45,6 +45,12 @@ Pass `--help` to see all options: npx create-factory@latest --help ``` +Platform projects are created in the US region by default. To create the project in the EU instead, pass `--region eu`: + +```bash +npx create-factory@latest my-mastra-factory --region eu +``` + ## Documentation - [create-factory CLI reference](https://factory.mastra.ai/reference/create-factory) diff --git a/mastracode/mastra-factory/src/create.test.ts b/mastracode/mastra-factory/src/create.test.ts index d153a7795c7..2d9c5c4a7e2 100644 --- a/mastracode/mastra-factory/src/create.test.ts +++ b/mastracode/mastra-factory/src/create.test.ts @@ -90,7 +90,6 @@ beforeEach(() => { { id: 'org_123', name: 'Acme', role: 'admin', isCurrent: true }, { id: 'org_456', name: 'Beta', role: 'member', isCurrent: false }, ]); - clack.select.mockResolvedValue('eu'); platform.createServerProject.mockResolvedValue({ id: 'proj_abc', slug: 'my-factory', name: 'my-factory' }); platform.mintOrgApiKey.mockResolvedValue('sk_live_test'); platform.ensureProductionEnvironment.mockResolvedValue('env_production'); @@ -296,7 +295,7 @@ describe('create (platform provisioning)', () => { token: 'wos-token', orgId: 'org_123', projectId: 'proj_abc', - region: 'eu', + region: 'us', }); // Other .env.example placeholders untouched. @@ -306,19 +305,13 @@ describe('create (platform provisioning)', () => { // Platform pipeline hit in order. expect(cliAuth.getToken).toHaveBeenCalledTimes(1); expect(cliAuth.resolveCurrentOrg).toHaveBeenCalledWith('wos-token', { forcePrompt: true }); - expect(clack.select).toHaveBeenCalledWith({ - message: 'Where should your Factory project run?', - options: [ - { value: 'us', label: '🇺🇸 us' }, - { value: 'eu', label: '🇪🇺 eu' }, - ], - initialValue: 'us', - }); + // Region defaults to us without prompting. + expect(clack.select).not.toHaveBeenCalled(); expect(platform.createServerProject).toHaveBeenCalledWith({ token: 'wos-token', orgId: 'org_123', name: 'my-factory', - region: 'eu', + region: 'us', }); expect(platform.mintOrgApiKey).toHaveBeenCalledWith({ token: 'wos-token', @@ -330,7 +323,7 @@ describe('create (platform provisioning)', () => { orgId: 'org_123', projectId: 'proj_abc', name: 'my-factory', - regionId: 'aws-eu-central-1', + regionId: 'aws-us-west-2', }); // Success outro summarizes the provisioned infra so the user isn't @@ -396,22 +389,23 @@ describe('create (platform provisioning)', () => { expect(note).toContain('still provisioning'); }); - it('passes --region to project creation and skips the region picker', async () => { + it('passes --region eu to project creation and the database region', async () => { await create({ projectName: 'my-factory', template: PLATFORM_TEMPLATE_REPO, - region: 'us', + region: 'eu', analytics, }); expect(clack.select).not.toHaveBeenCalled(); - expect(platform.createServerProject).toHaveBeenCalledWith(expect.objectContaining({ region: 'us' })); + expect(platform.createServerProject).toHaveBeenCalledWith(expect.objectContaining({ region: 'eu' })); + expect(platform.ensureProductionEnvironment).toHaveBeenCalledWith(expect.objectContaining({ region: 'eu' })); expect(platform.attachNeonDatabase).toHaveBeenCalledWith({ token: 'wos-token', orgId: 'org_123', projectId: 'proj_abc', name: 'my-factory', - regionId: 'aws-us-west-2', + regionId: 'aws-eu-central-1', }); }); diff --git a/mastracode/mastra-factory/src/create.ts b/mastracode/mastra-factory/src/create.ts index c165976c842..d1da4c2d260 100644 --- a/mastracode/mastra-factory/src/create.ts +++ b/mastracode/mastra-factory/src/create.ts @@ -59,11 +59,6 @@ interface PlatformProvisionResult { databaseUrl: string; } -const PROJECT_REGION_OPTIONS = [ - { value: 'us', label: '🇺🇸 us' }, - { value: 'eu', label: '🇪🇺 eu' }, -] as const satisfies ReadonlyArray<{ value: ProjectRegion; label: string }>; - const NEON_REGION_BY_PROJECT_REGION = { eu: 'aws-eu-central-1', us: 'aws-us-west-2', @@ -296,17 +291,7 @@ async function runPlatformProvisioning({ p.log.info(`Using organization ${color.cyan(orgName)}.`); envAccumulator.MASTRA_ORGANIZATION_ID = orgId; - const projectRegion = - region ?? - (await p.select({ - message: 'Where should your Factory project run?', - options: [...PROJECT_REGION_OPTIONS], - initialValue: 'us', - })); - if (p.isCancel(projectRegion)) { - p.cancel('Operation cancelled'); - process.exit(0); - } + const projectRegion = region ?? 'us'; // 3. Project — session-auth POST /v1/server/projects. const projectSpinner = p.spinner(); diff --git a/mastracode/mastra-factory/src/index.ts b/mastracode/mastra-factory/src/index.ts index f35023798a1..55c5079a703 100644 --- a/mastracode/mastra-factory/src/index.ts +++ b/mastracode/mastra-factory/src/index.ts @@ -39,7 +39,7 @@ program ) .option('--no-platform', 'Skip Mastra platform provisioning and scaffold the self-hosted template') .option('--org ', 'Mastra organization id or name — skips the interactive org picker') - .option('--region ', 'Platform project region (eu or us); prompts when omitted') + .option('--region ', 'Platform project region (eu or us); defaults to us') .version(pkg.version, '-v, --version') .action(async (projectNameArg: string | undefined, args: CreateArgs) => { const region = args.region ? String(args.region) : undefined; From f9907987ad424313d14b9c77291bd8ef79a5b052 Mon Sep 17 00:00:00 2001 From: Abhi Aiyer Date: Thu, 12 Nov 2026 15:54:32 -0800 Subject: [PATCH 010/239] fix(factory): keep labels on GitHub pull request intake cards (#30250) ## Summary Factory stored every GitHub pull request with an empty label list, because the GitHub intake mapped labels for issues but not pull requests. Intake routes that match on labels (for example sending `security`-labeled items to a Security board) therefore never matched pull requests. Pull request intake items now carry their labels. ## Test plan - [x] `tsc --noEmit` in `mastracode/factory` - [x] `vitest run src/integrations/platform/github` - [x] Locally, `security`-labeled PRs in `mastra-ai/platform` landed on the Security board once labels were stored ELI5: Pull requests from GitHub now keep their labels. Rules that send items to a board by label, such as the `security` label, can now match pull requests too. ## Summary This change fixes GitHub pull request intake items in Factory. `listItems` mapped labels for issues but did not map them for pull requests. Pull request items therefore had no labels, and label-based intake routes could not match them. ## Changes - `mastracode/factory/src/integrations/platform/github/integration.ts`: In `listItems`, the pull request intake item now includes `labels: pullRequest.labels`. This line is added at the pull request item mapping, between `status` and `createdAt`. No lines are removed. - `.changeset/vast-masks-stand.md`: Adds a patch changeset for `@mastra/factory`. The changeset says pull request cards no longer lose their labels, so label routes such as `security` now apply to pull requests. ## Scope - 2 files changed, 6 lines added, 0 lines removed (per the pull request diff). - No exported or public declarations changed. ## Verification - The PR author reports that `tsc --noEmit` passed in `mastracode/factory`. - The PR author reports that `vitest run src/integrations/platform/github` ran. - The PR author reports a local check where `security`-labeled PRs in `mastra-ai/platform` landed on the Security board. These results come from the author and were not re-run in this review. - CI results are not available. Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/vast-masks-stand.md | 5 +++++ .../factory/src/integrations/platform/github/integration.ts | 1 + 2 files changed, 6 insertions(+) create mode 100644 .changeset/vast-masks-stand.md diff --git a/.changeset/vast-masks-stand.md b/.changeset/vast-masks-stand.md new file mode 100644 index 00000000000..c37267c7469 --- /dev/null +++ b/.changeset/vast-masks-stand.md @@ -0,0 +1,5 @@ +--- +'@mastra/factory': patch +--- + +Fixed GitHub pull request cards losing their labels, so intake routes that match on labels (for example `security`) now route pull requests too. diff --git a/mastracode/factory/src/integrations/platform/github/integration.ts b/mastracode/factory/src/integrations/platform/github/integration.ts index 455744a46df..3a16d0d7353 100644 --- a/mastracode/factory/src/integrations/platform/github/integration.ts +++ b/mastracode/factory/src/integrations/platform/github/integration.ts @@ -399,6 +399,7 @@ export class PlatformGithubIntegration implements FactoryIntegration { sourceId, title: pullRequest.title, status: pullRequest.state, + labels: pullRequest.labels, createdAt: pullRequest.createdAt, updatedAt: pullRequest.updatedAt, metadata: { From 724286f3dde526182d95cd7b380769b1e0b00122 Mon Sep 17 00:00:00 2001 From: Abhi Aiyer Date: Thu, 12 Nov 2026 15:55:48 -0800 Subject: [PATCH 011/239] feat(factory): let intake rules set descriptions on the cards they create (#30253) ## Summary Cards created by rules always started with an empty description, so integrations had nowhere to put upstream details such as an advisory's summary. `upsertLinkedWorkItem` decisions can now carry an optional `description` (up to 8,000 characters). It only seeds a newly created card and never overwrites an existing card's description. The Dependabot and Vanta intake PRs build on this. ## Test plan - [x] `vitest run src/rules/validation.test.ts` (new test: description kept, over-length rejected) - [x] `tsc --noEmit` in `mastracode/factory` ELI5: When the factory creates a new work card from an intake rule, the card can now start with a description. Cards that already exist keep their current description. ## Summary This change lets `upsertLinkedWorkItem` decisions carry an optional `description`. The description seeds only newly created cards. Existing cards keep their descriptions. ## Changes - **Type** (`mastracode/factory/src/rules/types.ts`): Adds optional `description?: string` to `FactoryUpsertLinkedWorkItemDecision`. The doc comment states that the value seeds only a card being created. - **Validation** (`mastracode/factory/src/rules/validation.ts`): Adds `MAX_DESCRIPTION_LENGTH = 8000`. Adds `'description'` to the allowed decision keys. When `description` is present, it passes through `boundedString` with the 8,000-character limit. Values over the limit are rejected. - **Dispatcher** (`mastracode/factory/src/rules/dispatcher.ts`): Adds `description` to the work-item upsert input only when the decision value is truthy. Otherwise the field is omitted. - **Tests** (`mastracode/factory/src/rules/validation.test.ts`): Adds 18 lines of tests. Per the raw summary, they cover retaining a description and rejecting values over 8,000 characters with `FactoryRuleValidationError`. The test body was not in the inspected output. - **Changeset** (`.changeset/jolly-geckos-change.md`): Adds a minor release entry for `@mastra/factory`. ## Scope - Diff: 5 files, 37 lines added, 0 lines removed. - No exported declarations other than the new interface property. ## Not verified - The raw summary says the description is trimmed and must be nonempty. The inspected diff does not show `boundedString`, so this summary does not confirm trimming or the nonempty rule. - Test results (`vitest`) and type checks (`tsc --noEmit`) were not run in this review. Results are not available. Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/jolly-geckos-change.md | 5 +++++ mastracode/factory/src/rules/dispatcher.ts | 1 + mastracode/factory/src/rules/types.ts | 2 ++ .../factory/src/rules/validation.test.ts | 18 ++++++++++++++++++ mastracode/factory/src/rules/validation.ts | 11 +++++++++++ 5 files changed, 37 insertions(+) create mode 100644 .changeset/jolly-geckos-change.md diff --git a/.changeset/jolly-geckos-change.md b/.changeset/jolly-geckos-change.md new file mode 100644 index 00000000000..6992b8836da --- /dev/null +++ b/.changeset/jolly-geckos-change.md @@ -0,0 +1,5 @@ +--- +'@mastra/factory': minor +--- + +Intake rules can now set a description on the cards they create, so cards from integrations show the item's details instead of an empty description. diff --git a/mastracode/factory/src/rules/dispatcher.ts b/mastracode/factory/src/rules/dispatcher.ts index 88c67f673e7..118dbc8f086 100644 --- a/mastracode/factory/src/rules/dispatcher.ts +++ b/mastracode/factory/src/rules/dispatcher.ts @@ -1889,6 +1889,7 @@ export class FactoryDecisionDispatcher { externalSource: externalSourceForDecision(decision), parentWorkItemId, title: decision.title, + ...(decision.description ? { description: decision.description } : {}), board: decision.board, stages: [entryStage], sessions: {}, diff --git a/mastracode/factory/src/rules/types.ts b/mastracode/factory/src/rules/types.ts index 25e6084b2c5..5583b6bfae9 100644 --- a/mastracode/factory/src/rules/types.ts +++ b/mastracode/factory/src/rules/types.ts @@ -660,6 +660,8 @@ export interface FactoryUpsertLinkedWorkItemDecision extends FactoryCommitDecisi source: WorkItemSource; sourceKey: string; title: string; + /** The new card's own description. Only seeds a card being created; an existing card's is left alone. */ + description?: string; url: string | null; stage: FactoryRuleStage; /** diff --git a/mastracode/factory/src/rules/validation.test.ts b/mastracode/factory/src/rules/validation.test.ts index d2f48ed5c51..a412a8f57ef 100644 --- a/mastracode/factory/src/rules/validation.test.ts +++ b/mastracode/factory/src/rules/validation.test.ts @@ -30,6 +30,24 @@ describe('Factory rule validation', () => { }, ); + it('keeps a linked-item description and rejects one over the length limit', () => { + const linked = { + type: 'upsertLinkedWorkItem', + idempotencyKey: 'vuln:1', + board: 'work', + stage: 'intake', + source: 'manual', + sourceKey: 'vuln:1', + title: 'Upgrade lodash', + description: '**Severity:** high', + url: null, + }; + expect(validateFactoryRuleDecision(linked)).toEqual(linked); + expect(() => validateFactoryRuleDecision({ ...linked, description: 'x'.repeat(8001) })).toThrow( + FactoryRuleValidationError, + ); + }); + it('accepts a saved linked-item decision that still carries a claim key and drops the claim', () => { const unclaimed = { type: 'upsertLinkedWorkItem', diff --git a/mastracode/factory/src/rules/validation.ts b/mastracode/factory/src/rules/validation.ts index 18222953dea..ea3b69bdcaa 100644 --- a/mastracode/factory/src/rules/validation.ts +++ b/mastracode/factory/src/rules/validation.ts @@ -17,6 +17,7 @@ const MAX_VERSION_LENGTH = 128; const MAX_IDEMPOTENCY_KEY_LENGTH = 256; const MAX_REASON_LENGTH = 512; const MAX_TITLE_LENGTH = 512; +const MAX_DESCRIPTION_LENGTH = 8000; const MAX_MESSAGE_LENGTH = 8_192; const MAX_ARGUMENTS_LENGTH = 4_096; export const MAX_ROLE_LENGTH = 32; @@ -337,6 +338,7 @@ export function validateFactoryRuleDecision(value: unknown, causalDepth = 0): Fa // Decisions saved before claims were dropped still carry it; it is ignored. 'claimKey', 'title', + 'description', 'url', 'stage', 'skipRules', @@ -363,6 +365,15 @@ export function validateFactoryRuleDecision(value: unknown, causalDepth = 0): Fa source: enumValue(value.source, WORK_ITEM_SOURCES, 'Factory linked work item source'), sourceKey: boundedString(value.sourceKey, 'Factory linked work item sourceKey', MAX_SOURCE_KEY_LENGTH), title: boundedString(value.title, 'Factory linked work item title', MAX_TITLE_LENGTH), + ...(value.description === undefined + ? {} + : { + description: boundedString( + value.description, + 'Factory linked work item description', + MAX_DESCRIPTION_LENGTH, + ), + }), url, stage: boardIdentifier(value.stage, 'Factory linked work item stage'), ...(value.skipRules === true ? { skipRules: true } : {}), From 9f16f63a66455a3fe79f008249a83480a9a61971 Mon Sep 17 00:00:00 2001 From: Ward Peeters Date: Fri, 13 Nov 2026 00:59:52 +0100 Subject: [PATCH 012/239] fix(factory): run card phases as the Factory, and let the people following a card approve what it waits on (#30146) Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/factory-phase-session-owner.md | 35 + .../factory-ui/src/hooks/useWorkItems.ts | 6 + .../chat/components/TeammateSessionLine.tsx | 5 +- .../components/TranscriptNotifications.tsx | 97 ++- ...anscriptApprovalNotifications.msw.test.tsx | 194 ++++++ .../ui/domains/chat/services/transcript.ts | 2 + .../workspaces/components/SessionListItem.tsx | 5 + .../components/SessionMenuItems.tsx | 19 +- .../workspaces/components/SessionNavRow.tsx | 13 +- .../SessionsSectionFollowedCards.msw.test.tsx | 270 ++++++++ .../hooks/useAnswerParkedApproval.ts | 27 + .../workspaces/hooks/useSessionListRows.ts | 10 +- .../services/sessionPresentation.ts | 9 +- .../workspaces/services/sessionRows.ts | 55 +- .../workspaces/services/user-sessions.ts | 20 + .../ThreadPageTeammateSession.msw.test.tsx | 17 + mastracode/factory/README.md | 8 +- mastracode/factory/package.json | 1 + mastracode/factory/src/factory.ts | 1 + .../factory/src/integrations/github/routes.ts | 13 +- .../src/routes/source-control-sessions.ts | 134 +++- mastracode/factory/src/routes/surface.test.ts | 318 ++++++++- mastracode/factory/src/routes/surface.ts | 87 ++- .../factory/src/rules/dispatch-errors.ts | 10 + .../factory/src/rules/dispatcher.test.ts | 238 ++++++- mastracode/factory/src/rules/dispatcher.ts | 68 +- .../src/rules/start-coordinator.test.ts | 63 ++ .../factory/src/rules/start-coordinator.ts | 14 +- .../factory/src/rules/transition-service.ts | 5 +- .../factory/src/session/factory-session.ts | 45 +- .../src/storage/domains/audit/actors.ts | 8 +- .../src/storage/domains/projects/base.ts | 12 + .../src/storage/domains/work-items/base.ts | 42 +- .../src/tools/approval-answer-resume.test.ts | 652 ++++++++++++++++++ .../factory/src/tools/approval-tools.test.ts | 198 +++++- .../factory/src/tools/approval-tools.ts | 156 ++++- mastracode/factory/src/tools/reports.test.ts | 31 +- mastracode/factory/src/tools/reports.ts | 16 +- mastracode/factory/src/tools/run-watch.ts | 41 +- .../factory/src/tools/session-tools.test.ts | 80 ++- mastracode/factory/src/tools/session-tools.ts | 23 +- .../factory/src/tools/work-item-tools.test.ts | 53 ++ .../factory/src/tools/work-item-tools.ts | 18 +- pnpm-lock.yaml | 3 + 44 files changed, 2955 insertions(+), 167 deletions(-) create mode 100644 .changeset/factory-phase-session-owner.md create mode 100644 mastracode/factory-ui/src/ui/domains/chat/components/__tests__/TranscriptApprovalNotifications.msw.test.tsx create mode 100644 mastracode/factory-ui/src/ui/domains/workspaces/components/__tests__/SessionsSectionFollowedCards.msw.test.tsx create mode 100644 mastracode/factory-ui/src/ui/domains/workspaces/hooks/useAnswerParkedApproval.ts create mode 100644 mastracode/factory/src/tools/approval-answer-resume.test.ts diff --git a/.changeset/factory-phase-session-owner.md b/.changeset/factory-phase-session-owner.md new file mode 100644 index 00000000000..9179d964640 --- /dev/null +++ b/.changeset/factory-phase-session-owner.md @@ -0,0 +1,35 @@ +--- +'@mastra/factory': patch +--- + +Fixed who owns the sessions a Factory card runs in, and who can approve what they wait on. + +**Who owns a card's phase session** + +- In a Factory that runs card work on the organization's model keys (the `factory` and `hybrid` credential settings), every new phase session now belongs to the Factory itself and uses the organization's keys and the Factory's default model. That holds whoever moved the card: a person, an agent, a webhook or a rule. Before, it ran as whoever connected the repository, or as the person who approved the move. +- The person who moved or approved the card stays on record as the one who did it. When they move a card from their own session, that session follows the card, so it hears when the phase waits on someone and can answer from there. +- If the organization has neither a model key nor a provider of its own, the run stops with a clear "add an organization key or provider" message and is not tried again on its own. Add one, then press Retry on the card. +- In a Factory on personal credentials there are no organization keys, so a phase runs as the person who moved or approved the card (or whose session's agent moved it), and otherwise as the person who created the Factory. + +Sessions that already exist keep their owner. + +**Approving a waiting tool call** + +- The person who asked for the work, and anyone whose session follows the card, can approve or decline any tool call the phase session is waiting on, a plan or any other tool that asks first. They can do it from their own session in the sidebar, with `factory_answer_approval`, or over HTTP: + + ```http + POST /web/user-sessions/:sessionId/parked-approval + { "decision": "approve" } + ``` + + Add `toolCallId` when the session waits on more than one approval. Questions that need a typed answer are still answered in the session. + +- A session following the card is told when the phase session waits on a yes or no, for a plan or any other tool, with the call to answer it. In the chat that notice now has Approve and Decline buttons and a link to open the waiting session; a notice about a question that needs a typed answer has the link only. +- Nobody is asked to approve what a phase approves itself: when a phase's `exitTool` has `autoApprove` and the card matches `autoApproveWhen`, the run carries on without a notice. This now works for any exit tool that pauses for a yes or no, not only `submit_plan`. +- When two people answer the same call at once, one answer is used and the other is told the call was already answered. +- The run then carries on as the phase session's owner. Before, it carried on as whoever answered, and could fail with "the request has no authenticated user". +- Following moves with a session: after a hand-over, the session's new owner can answer and the old one cannot. + +**Sidebar** + +A card's phase sessions now show under the session that asked for the work when child sessions are revealed, marked "run by Factory" when the Factory owns them, and that session shows "waiting on you", with Approve and Decline in its menu, while one of them waits on the viewer. diff --git a/mastracode/factory-ui/src/hooks/useWorkItems.ts b/mastracode/factory-ui/src/hooks/useWorkItems.ts index 6f9d2282e3b..6c4daff1a69 100644 --- a/mastracode/factory-ui/src/hooks/useWorkItems.ts +++ b/mastracode/factory-ui/src/hooks/useWorkItems.ts @@ -385,6 +385,12 @@ function withoutCard(cached: BoardSnapshot | BoardPhasesSnapshot, id: string): B }; } +/** Whether a session is parked; `undefined` until the cards holding sessions have been read. */ +export function useSessionParked(factoryProjectId: string | undefined, sessionId: string): boolean | undefined { + const { data } = useSidebarWorkItemsQuery(factoryProjectId); + return data?.parkedSessionIds.includes(sessionId); +} + /** * Materialize a work item (the server upserts on `sourceKey`, so acting twice * on the same issue reuses the card). The cached cards are patched in place. diff --git a/mastracode/factory-ui/src/ui/domains/chat/components/TeammateSessionLine.tsx b/mastracode/factory-ui/src/ui/domains/chat/components/TeammateSessionLine.tsx index c6bec597730..eba03ebf0fc 100644 --- a/mastracode/factory-ui/src/ui/domains/chat/components/TeammateSessionLine.tsx +++ b/mastracode/factory-ui/src/ui/domains/chat/components/TeammateSessionLine.tsx @@ -4,6 +4,7 @@ import { useParams } from 'react-router'; import { useFactoryAuth } from '../../../../hooks/useFactoryAuth'; import { useUserSessionQuery } from '../../../../hooks/useWorkspaces'; +import { isFactoryOwnedSession } from '../../workspaces/services/sessionPresentation'; import { TakeOwnershipDialog } from './TakeOwnershipDialog'; export function TeammateSessionLine() { @@ -23,7 +24,9 @@ export function TeammateSessionLine() { )} - You’re steering {owner?.name ?? 'a teammate'}’s session + {isFactoryOwnedSession(session) + ? 'You’re steering the Factory’s session' + : `You’re steering ${owner?.name ?? 'a teammate'}’s session`} {canTakeOwnership && } diff --git a/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx b/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx index b9b97113939..8caaae7a6c1 100644 --- a/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx +++ b/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx @@ -1,7 +1,16 @@ import { NotificationActivity } from '@mastra/playground-ui/components/ai/activity'; +import { Button } from '@mastra/playground-ui/components/Button'; +import { Txt } from '@mastra/playground-ui/components/Txt'; import { cn } from '@mastra/playground-ui/utils/cn'; +import { useMutation, useQueryClient } from '@tanstack/react-query'; import { Bell, CircleDot } from 'lucide-react'; import type { ReactNode } from 'react'; +import { Link, useParams } from 'react-router'; + +import { useApiConfig } from '../../../../api/config'; +import { queryKeys } from '../../../../api/keys'; +import { useSessionParked } from '../../../../hooks/useWorkItems'; +import { answerParkedApproval } from '../../workspaces/services/user-sessions'; import { PullRequestStatusIcon } from '../../factory/components/PullRequestStatusIcon'; import type { MessageEntry, NotificationEntry, NotificationSummaryEntry } from '../services/transcript'; @@ -55,7 +64,9 @@ function notificationPresentation(entry: NotificationEntry): { state: string; ic export function NotificationCard({ entry }: { entry: NotificationEntry }) { const presentation = notificationPresentation(entry); const url = notificationUrl(entry); - return ( + const { factoryId } = useParams<{ factoryId: string }>(); + const waiting = waitingSession(entry); + const activity = ( ); + if (!waiting || !factoryId) return activity; + return ( +
+ {activity} + +
+ ); +} + +/** The session a notification says is waiting on someone, and the call a yes or no would answer. */ +interface WaitingSession { + sessionId: string; + threadId: string; + /** Set when the session waits on a bare yes or no; a typed answer is given in the session itself. */ + toolCallId?: string; +} + +function waitingSession(entry: NotificationEntry): WaitingSession | undefined { + if (entry.notifKind !== 'approval' && entry.notifKind !== 'blocked') return undefined; + const sessionId = entry.attributes?.['from-session']; + if (typeof sessionId !== 'string' || !sessionId) return undefined; + const threadId = entry.attributes?.['from-thread']; + const toolCallId = entry.attributes?.['tool-call-id']; + return { + sessionId, + threadId: typeof threadId === 'string' && threadId ? threadId : sessionId, + ...(entry.attributes?.['waiting-for'] === 'approval' && typeof toolCallId === 'string' && toolCallId + ? { toolCallId } + : {}), + }; +} + +/** + * Opens the waiting session, and answers its call from here where a yes or no is all it needs. + * The server decides who may answer; its refusal is shown in place of the buttons. + */ +function WaitingSessionActions({ factoryId, waiting }: { factoryId: string; waiting: WaitingSession }) { + const { baseUrl } = useApiConfig(); + const queryClient = useQueryClient(); + const parked = useSessionParked(factoryId, waiting.sessionId); + const { toolCallId } = waiting; + const answer = useMutation({ + mutationKey: ['answer-parked-approval', waiting.sessionId, toolCallId], + mutationFn: (decision: 'approve' | 'decline') => + answerParkedApproval(baseUrl, waiting.sessionId, decision, toolCallId), + onSettled: () => void queryClient.invalidateQueries({ queryKey: queryKeys.workItems(factoryId) }), + }); + const outcome = answer.isSuccess + ? answer.variables === 'approve' + ? 'Approved' + : 'Declined' + : answer.isError + ? answer.error.message + : parked === false + ? 'Answered' + : undefined; + + return ( +
+ {toolCallId && !outcome && parked && ( + <> + + + + )} + {toolCallId && outcome && ( + + {outcome} + + )} + +
+ ); } export function NotificationSummaryCard({ entry }: { entry: NotificationSummaryEntry }) { @@ -159,6 +253,7 @@ function signalNotifications(entry: MessageEntry): Array, notifKind = 'blocked'): NotificationEntry { + return { + kind: 'notification', + id: 'waiting', + source: 'factory', + notifKind, + priority: 'urgent', + message: 'The plan session for #49 is waiting on submit_plan and needs an answer.', + attributes: { 'from-session': PHASE, 'from-thread': PHASE, 'work-item': '#49', role: 'plan', ...attributes }, + }; +} + +const approvalNotice = () => + waitingNotice({ 'waiting-for': 'approval', 'parked-tool': 'submit_plan', 'tool-call-id': 'call_plan' }); + +describe('A notification that a followed card’s phase session waits on someone', () => { + let parkedSessionIds: string[]; + let answers: Array<{ sessionId: unknown; body: unknown }>; + let refusal: { status: number; error: string } | undefined; + + beforeEach(() => { + parkedSessionIds = [PHASE]; + answers = []; + refusal = undefined; + server.use( + http.get(`${TEST_BASE_URL}/web/factory/projects/${factoryId}/work-items`, () => + HttpResponse.json({ workItems: [], runningSessionIds: [], parkedSessionIds }), + ), + http.post(`${TEST_BASE_URL}/web/user-sessions/:sessionId/parked-approval`, async ({ params, request }) => { + if (refusal) return HttpResponse.json({ error: refusal.error }, { status: refusal.status }); + const body = (await request.json()) as { decision: string }; + answers.push({ sessionId: params.sessionId, body }); + parkedSessionIds = []; + return HttpResponse.json({ answered: body.decision, sessionId: params.sessionId, toolCallId: 'call_plan' }); + }), + ); + }); + + function renderNotice(entry: TimelineEntry) { + const view = renderWithProviders( + + + {}} onRespond={() => {}} />} + /> + + , + ); + return { ...view, notice: within(screen.getByRole('group', { name: 'Waiting session' })) }; + } + + it.each([ + ['Approve', 'approve', 'Approved'], + ['Decline', 'decline', 'Declined'], + ])('answers the waiting call with %s, right in the chat, and then says so', async (button, decision, outcome) => { + const { client, notice } = renderNotice(approvalNotice()); + + await userEvent.click(await notice.findByRole('button', { name: button })); + await waitForMutationsIdle(client); + + expect(answers).toEqual([{ sessionId: PHASE, body: { decision, toolCallId: 'call_plan' } }]); + expect(notice.getByText(outcome)).toBeVisible(); + expect(notice.queryByRole('button', { name: 'Approve' })).not.toBeInTheDocument(); + expect(notice.queryByRole('button', { name: 'Decline' })).not.toBeInTheDocument(); + }); + + it('offers the answer on the notice as the chat stores it, so it is still there after a reload', async () => { + const createdAt = new Date('2026-07-15T10:00:00.000Z'); + const { client, notice } = renderNotice({ + kind: 'message', + id: 'stored', + message: { + id: 'stored', + role: 'signal', + createdAt, + content: { + format: 2, + parts: [{ type: 'text', text: 'The plan session for #49 is waiting on submit_plan and needs an answer.' }], + metadata: { + signal: { + id: 'stored', + type: 'notification', + tagName: 'notification', + createdAt: createdAt.toISOString(), + attributes: { + id: 'notification-1', + source: 'factory', + type: 'blocked', + kind: 'blocked', + priority: 'urgent', + status: 'blocked', + 'from-session': PHASE, + 'from-thread': PHASE, + 'waiting-for': 'approval', + 'parked-tool': 'submit_plan', + 'tool-call-id': 'call_plan', + }, + }, + }, + }, + }, + }); + + await userEvent.click(await notice.findByRole('button', { name: 'Approve' })); + await waitForMutationsIdle(client); + + expect(answers).toEqual([{ sessionId: PHASE, body: { decision: 'approve', toolCallId: 'call_plan' } }]); + }); + + it('links to the session that waits', async () => { + const { notice } = renderNotice(approvalNotice()); + + expect(await notice.findByRole('link', { name: 'Open session' })).toHaveAttribute( + 'href', + `/factories/${factoryId}/workspaces/${PHASE}/threads/${PHASE}`, + ); + }); + + it('offers the same for a tool call held until a person allows it', async () => { + const { notice } = renderNotice( + waitingNotice( + { 'waiting-for': 'approval', 'tool-name': 'ship_release', 'tool-call-id': 'call_release' }, + 'approval', + ), + ); + + expect(await notice.findByRole('button', { name: 'Approve' })).toBeVisible(); + expect(notice.getByRole('button', { name: 'Decline' })).toBeVisible(); + }); + + it('says the call was answered, with nothing left to press, once the session no longer waits', async () => { + parkedSessionIds = []; + const { client, notice } = renderNotice(approvalNotice()); + await waitForMutationsIdle(client); + + expect(await notice.findByText('Answered')).toBeVisible(); + expect(notice.queryByRole('button', { name: 'Approve' })).not.toBeInTheDocument(); + expect(notice.getByRole('link', { name: 'Open session' })).toBeVisible(); + }); + + it('says why when someone else answered first, and stops offering the answer', async () => { + refusal = { status: 409, error: 'That call was already answered: someone else got there first.' }; + const { client, notice } = renderNotice(approvalNotice()); + + await userEvent.click(await notice.findByRole('button', { name: 'Approve' })); + await waitForMutationsIdle(client); + + await waitFor(() => + expect(notice.getByText('That call was already answered: someone else got there first.')).toBeVisible(), + ); + expect(notice.queryByRole('button', { name: 'Approve' })).not.toBeInTheDocument(); + }); + + it('says why when the viewer may not answer, and leaves the session to open', async () => { + refusal = { + status: 403, + error: "Only the session's owner, an organization admin, or someone following its card can answer.", + }; + const { client, notice } = renderNotice(approvalNotice()); + + await userEvent.click(await notice.findByRole('button', { name: 'Decline' })); + await waitForMutationsIdle(client); + + await waitFor(() => expect(notice.getByText(/Only the session's owner/)).toBeVisible()); + expect(notice.getByRole('link', { name: 'Open session' })).toBeVisible(); + }); + + it('only links to the session when it waits on a typed answer, which a yes or no cannot give', async () => { + const { client, notice } = renderNotice( + waitingNotice({ 'parked-tool': 'ask_user', 'tool-call-id': 'call_question' }), + ); + await waitForMutationsIdle(client); + + expect(notice.getByRole('link', { name: 'Open session' })).toBeVisible(); + expect(notice.queryByRole('button', { name: 'Approve' })).not.toBeInTheDocument(); + expect(notice.queryByText('Answered')).not.toBeInTheDocument(); + }); +}); diff --git a/mastracode/factory-ui/src/ui/domains/chat/services/transcript.ts b/mastracode/factory-ui/src/ui/domains/chat/services/transcript.ts index 1d9dd7ca18a..1937c937501 100644 --- a/mastracode/factory-ui/src/ui/domains/chat/services/transcript.ts +++ b/mastracode/factory-ui/src/ui/domains/chat/services/transcript.ts @@ -71,6 +71,8 @@ export interface NotificationEntry { notifKind?: string; priority?: string; metadata?: Record; + /** What the sender said about the notification, e.g. which session sent it and what it waits on. */ + attributes?: Record; } export interface NotificationSummaryEntry { diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionListItem.tsx b/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionListItem.tsx index e9b37f247cc..f77e4c4f3ff 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionListItem.tsx +++ b/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionListItem.tsx @@ -2,6 +2,7 @@ import { toast } from '@mastra/playground-ui/components/Toaster'; import type { ReactNode } from 'react'; import { useLocation } from 'react-router'; +import { useAnswerParkedApproval } from '../hooks/useAnswerParkedApproval'; import { updatePinnedSessions } from '../hooks/usePinnedSessions'; import { useRegenerateSessionTitle } from '../hooks/useRegenerateSessionTitle'; import { useSessionVisibility } from '../hooks/useSessionVisibility'; @@ -37,6 +38,7 @@ export function SessionListItem({ const location = useLocation(); const { regenerate, regenerating } = useRegenerateSessionTitle(factoryId, row.session.sessionId); const { changeVisibility, changing } = useSessionVisibility(factoryId, row.session.sessionId); + const { answer, answering } = useAnswerParkedApproval(factoryId, row.waitingSessionId); const ownUserSession = row.origin === 'user' && row.ownedByViewer; async function handleVisibilityChange(visibility: UserSessionVisibility) { @@ -52,6 +54,7 @@ export function SessionListItem({ onDelete(row) : undefined} onRegenerateTitle={row.canRegenerateTitle ? regenerate : undefined} regeneratingTitle={regenerating} + onAnswerApproval={answer} + answeringApproval={answering} visibility={row.origin === 'user' ? row.session.visibility : undefined} // Slack threads keep the visibility they were created with; the server refuses a change. onVisibilityChange={ diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionMenuItems.tsx b/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionMenuItems.tsx index c0056c11e9b..2573b2f3c6a 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionMenuItems.tsx +++ b/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionMenuItems.tsx @@ -1,7 +1,7 @@ import { ContextMenu } from '@mastra/playground-ui/components/ContextMenu'; import { DropdownMenu } from '@mastra/playground-ui/components/DropdownMenu'; import { cn } from '@mastra/playground-ui/utils/cn'; -import { ExternalLink, Lock, Pin, PinOff, RefreshCw, Trash2, Users } from 'lucide-react'; +import { Check, ExternalLink, Lock, Pin, PinOff, RefreshCw, Trash2, Users, X } from 'lucide-react'; import { Link } from 'react-router'; import { SourceIcon } from '../../factory/components/BoardIcons'; @@ -16,6 +16,8 @@ export function SessionMenuItems({ onDelete, onRegenerateTitle, regeneratingTitle, + onAnswerApproval, + answeringApproval, visibility, onVisibilityChange, changingVisibility, @@ -28,6 +30,8 @@ export function SessionMenuItems({ onDelete?: () => void; onRegenerateTitle?: () => void; regeneratingTitle?: boolean; + onAnswerApproval?: (decision: 'approve' | 'decline') => void; + answeringApproval?: boolean; visibility?: 'org' | 'private'; onVisibilityChange?: (visibility: 'org' | 'private') => void; changingVisibility?: boolean; @@ -47,6 +51,19 @@ export function SessionMenuItems({ ))} + {onAnswerApproval ? ( + <> + onAnswerApproval('approve')}> + + Approve + + onAnswerApproval('decline')}> + + Decline + + + + ) : null} onPinChange(!pinned)}> {pinned ? : } {pinned ? 'Unpin' : 'Pin session'} diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionNavRow.tsx b/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionNavRow.tsx index 91edd93075c..be010056b57 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionNavRow.tsx +++ b/mastracode/factory-ui/src/ui/domains/workspaces/components/SessionNavRow.tsx @@ -39,6 +39,7 @@ import type { LivePullRequestStatus } from '../../../../hooks/useWorkspacePullRe export function SessionNavRow({ name, label, + runByFactory, level, title, url, @@ -56,6 +57,8 @@ export function SessionNavRow({ onPinChange, onDelete, onRegenerateTitle, + onAnswerApproval, + answeringApproval, regeneratingTitle, visibility, onVisibilityChange, @@ -68,6 +71,8 @@ export function SessionNavRow({ name: string; /** Shown instead of the name, which stays in the accessible name: a child session's phase. */ label?: string; + /** The Factory owns this session, though it is listed under a person's. */ + runByFactory?: boolean; /** Indent level: 1 for a card's child sessions. */ level?: number; /** Hover tooltip, typically the branch name. */ @@ -94,6 +99,9 @@ export function SessionNavRow({ onDelete?: () => void; /** Omitted for sessions the viewer does not own: the server only lets owners rename. */ onRegenerateTitle?: () => void; + /** Set while a followed card's phase session waits on an approval this viewer may give. */ + onAnswerApproval?: (decision: 'approve' | 'decline') => void; + answeringApproval?: boolean; regeneratingTitle?: boolean; /** Private rows show a sharing popover; shared rows have no visibility badge. */ visibility?: 'org' | 'private'; @@ -131,7 +139,7 @@ export function SessionNavRow({ to={url} state={from ? { from } : undefined} aria-current={active ? 'page' : undefined} - aria-label={label ? `${label}: ${name}` : name} + aria-label={[runByFactory ? 'Run by Factory' : undefined, label, name].filter(Boolean).join(': ')} aria-describedby={statusLabel ? statusId : undefined} aria-disabled={disabled || loading || undefined} tabIndex={disabled || loading ? -1 : undefined} @@ -164,6 +172,7 @@ export function SessionNavRow({ } > {label ?? name} + {runByFactory ? run by Factory : null} {pinned && !loading ? ( @@ -183,6 +192,8 @@ export function SessionNavRow({ onDelete, onRegenerateTitle, regeneratingTitle, + onAnswerApproval, + answeringApproval, visibility, onVisibilityChange, changingVisibility, diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/components/__tests__/SessionsSectionFollowedCards.msw.test.tsx b/mastracode/factory-ui/src/ui/domains/workspaces/components/__tests__/SessionsSectionFollowedCards.msw.test.tsx new file mode 100644 index 00000000000..d5187eb03b7 --- /dev/null +++ b/mastracode/factory-ui/src/ui/domains/workspaces/components/__tests__/SessionsSectionFollowedCards.msw.test.tsx @@ -0,0 +1,270 @@ +import { Sidebar } from '@mastra/playground-ui/components/Sidebar'; +import { screen, waitFor, within } from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; +import { http, HttpResponse } from 'msw'; +import { MemoryRouter, Route, Routes } from 'react-router'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; + +import { workBoardCatalog } from '../../../../../../e2e/ui/board-catalog'; +import { server } from '../../../../../../e2e/ui/msw-server'; +import { TEST_BASE_URL, renderWithProviders, waitForMutationsIdle } from '../../../../../../e2e/ui/render'; +import type { BoardCatalogResponse } from '../../../../../api/types'; +import { ChatSessionContext } from '../../../chat/context/ChatSessionContext'; +import type { WorkItem, WorkItemSessionRef } from '../../../factory/services/workItems'; +import type { FactoryUserSession } from '../../services/user-sessions'; +import { SessionsSection } from '../SessionsSection'; +import { closeSessionProperties, openSessionProperties } from './fixtures/sessionProperties'; +import { LIVE_SESSION, stubSessionsFactory, testChatSession } from './fixtures/sessionsSection'; + +const factoryId = 'fp-1'; +const projectRepositoryId = 'ghp-1'; + +type WireWorkItem = Omit & { + factoryProjectId: string; + externalSource: null; +}; + +function session(sessionId: string, title: string, branch: string): FactoryUserSession { + return { + id: `row-${sessionId}`, + sessionId, + projectRepositoryId, + orgId: 'org-1', + userId: 'user-1', + visibility: 'org', + title, + branch, + baseBranch: 'main', + sandboxId: null, + sandboxWorkdir: null, + materializedAt: '2026-09-04T10:00:00.000Z', + createdAt: '2026-09-04T10:00:00.000Z', + updatedAt: '2026-09-04T10:00:00.000Z', + }; +} + +const OWNER = 'user-owner'; +const planSession = { ...session('plan-session', 'Plan fix login', 'factory/issue-1'), userId: OWNER }; +const docsSession = { ...session('docs-session', 'Write docs', 'factory/issue-2'), userId: OWNER }; +// The viewer asked for "Fix login" from this session, so it follows that card. +const requesterSession = { + ...session('requester-session', 'Ask for a login fix', 'user/session-requester'), + followedWorkItemIds: ['fix-login'], +}; +// A teammate asked for the docs from their own shared session. The viewer follows nothing there. +const teammateSession = { + ...session('teammate-session', 'Teammate asks for docs', 'user/session-teammate'), + userId: 'user-teammate', + followedWorkItemIds: ['write-docs'], +}; +const scratchSession = { + ...session('scratch-session', 'Scratch notes', 'user/session-scratch'), + followedWorkItemIds: [], +}; + +const ref = (value: FactoryUserSession): WorkItemSessionRef => ({ + sessionId: value.sessionId, + branch: value.branch, + threadId: `${value.sessionId}-thread`, + startedBy: OWNER, +}); + +function card(id: string, title: string, sessions: WorkItem['sessions']): WireWorkItem { + return { + id, + orgId: 'org-1', + createdBy: 'user-1', + factoryProjectId: factoryId, + board: 'work', + externalSource: null, + parentWorkItemId: null, + title, + stages: ['execute'], + stageHistory: [], + sessions, + metadata: {}, + triageType: null, + acceptedAt: null, + description: null, + revision: 1, + createdAt: '2026-09-04T08:00:00.000Z', + updatedAt: '2026-09-04T10:00:00.000Z', + }; +} + +let parkedSessionIds: string[]; +let phaseSessionOwner: string; +let answers: Array<{ sessionId: string; body: unknown }>; + +beforeEach(() => { + localStorage.removeItem('mastracode.pinnedSessions'); + parkedSessionIds = []; + phaseSessionOwner = OWNER; + answers = []; + // The viewer is signed in as `user-1`, so sessions of other people read as teammates'. + window.__MASTRACODE_CONFIG__ = { authEnabled: true }; + stubSessionsFactory(factoryId, [projectRepositoryId]); + server.use( + http.get(`${TEST_BASE_URL}/auth/me`, () => + HttpResponse.json({ + authEnabled: true, + authenticated: true, + user: { userId: 'user-1', name: 'Romain', email: 'romain@example.com' }, + }), + ), + http.get(`${TEST_BASE_URL}/web/factory/projects/${factoryId}/boards`, () => + HttpResponse.json(workBoardCatalog satisfies BoardCatalogResponse), + ), + http.get(`${TEST_BASE_URL}/web/factory/projects/${factoryId}/sessions`, () => + HttpResponse.json({ + sessions: [ + { ...planSession, userId: phaseSessionOwner }, + docsSession, + requesterSession, + teammateSession, + scratchSession, + ], + }), + ), + http.get(`${TEST_BASE_URL}/web/factory/projects/${factoryId}/work-items`, () => + HttpResponse.json({ + workItems: [ + card('fix-login', 'Fix login', { work: ref(planSession) }), + card('write-docs', 'Write docs card', { work: ref(docsSession) }), + ], + parkedSessionIds, + }), + ), + http.post(`${TEST_BASE_URL}/web/user-sessions/:sessionId/parked-approval`, async ({ request, params }) => { + answers.push({ sessionId: String(params.sessionId), body: await request.json() }); + parkedSessionIds = []; + return HttpResponse.json({ answered: 'approve', sessionId: params.sessionId, toolCallId: 'call_release' }); + }), + ); +}); + +afterEach(() => { + delete window.__MASTRACODE_CONFIG__; +}); + +function renderSection() { + return renderWithProviders( + + + + + } /> + + + + , + ); +} + +function listItem(link: HTMLElement) { + const item = link.closest('li'); + if (!item) throw new Error('The row is not a list item'); + return item; +} + +describe("Sessions sidebar links a card's phase sessions to the session that asked for the work", () => { + it("lists the followed card's phase session under the asking session once child sessions are revealed", async () => { + const user = userEvent.setup(); + renderSection(); + const requester = await screen.findByRole('link', { name: 'Ask for a login fix' }); + expect(within(listItem(requester)).queryByRole('list')).not.toBeInTheDocument(); + + await openSessionProperties(user); + await user.click(await screen.findByRole('menuitemcheckbox', { name: 'Reveal child sessions' })); + await closeSessionProperties(user); + + const linked = await within(listItem(requester)).findByRole('link', { name: 'Plan fix login' }); + // A link to the card's session, which still has its own row: the session is not moved. + expect(linked).toHaveAttribute('href', expect.stringContaining('plan-session')); + expect(screen.getAllByRole('link', { name: 'Plan fix login' })).toHaveLength(2); + // Cards this session does not follow stay out of it, and sessions following nothing list nothing. + expect(within(listItem(requester)).queryByRole('link', { name: 'Write docs' })).not.toBeInTheDocument(); + const scratch = screen.getByRole('link', { name: 'Scratch notes' }); + expect(within(listItem(scratch)).queryByRole('list')).not.toBeInTheDocument(); + }); + + it('says the Factory runs the phase session listed under the session of the person who moved the card', async () => { + phaseSessionOwner = `factory-project:${factoryId}`; + const user = userEvent.setup(); + renderSection(); + const requester = await screen.findByRole('link', { name: 'Ask for a login fix' }); + + await openSessionProperties(user); + await user.click(await screen.findByRole('menuitemcheckbox', { name: 'Reveal child sessions' })); + await closeSessionProperties(user); + + const linked = await within(listItem(requester)).findByRole('link', { + name: 'Run by Factory: Plan fix login', + }); + expect(linked).toHaveAttribute('href', expect.stringContaining('plan-session')); + expect(within(linked).getByText('run by Factory')).toBeVisible(); + }); + + it('marks the asking session as waiting on you while the followed card waits on an approval', async () => { + parkedSessionIds = [planSession.sessionId]; + renderSection(); + + expect(await screen.findByRole('status', { name: 'Ask for a login fix waiting on you' })).toBeInTheDocument(); + expect(screen.queryByRole('status', { name: 'Scratch notes waiting on you' })).not.toBeInTheDocument(); + }); + + it("approves what the card waits on from the asking session's menu, answering the card's phase session", async () => { + parkedSessionIds = [planSession.sessionId]; + const user = userEvent.setup(); + const { client } = renderSection(); + await screen.findByRole('status', { name: 'Ask for a login fix waiting on you' }); + + await user.click(screen.getByRole('button', { name: 'Session actions for Ask for a login fix' })); + await user.click(await screen.findByRole('menuitem', { name: 'Approve' })); + await waitForMutationsIdle(client); + + await waitFor(() => expect(answers).toEqual([{ sessionId: 'plan-session', body: { decision: 'approve' } }])); + await waitFor(() => + expect(screen.queryByRole('status', { name: 'Ask for a login fix waiting on you' })).not.toBeInTheDocument(), + ); + }); + + it("declines it from the same menu, answering the card's phase session", async () => { + parkedSessionIds = [planSession.sessionId]; + const user = userEvent.setup(); + const { client } = renderSection(); + await screen.findByRole('status', { name: 'Ask for a login fix waiting on you' }); + + await user.click(screen.getByRole('button', { name: 'Session actions for Ask for a login fix' })); + await user.click(await screen.findByRole('menuitem', { name: 'Decline' })); + await waitForMutationsIdle(client); + + expect(answers).toEqual([{ sessionId: 'plan-session', body: { decision: 'decline' } }]); + }); + + it("does not ask the viewer to answer for a card only a teammate's session follows", async () => { + parkedSessionIds = [docsSession.sessionId]; + const user = userEvent.setup(); + renderSection(); + await screen.findByRole('link', { name: 'Teammate asks for docs' }); + // The card's own session still shows it is waiting; the teammate's row makes no claim on the viewer. + await screen.findByRole('status', { name: 'Write docs waiting on you' }); + + expect(screen.queryByRole('status', { name: 'Teammate asks for docs waiting on you' })).not.toBeInTheDocument(); + await user.click(screen.getByRole('button', { name: 'Session actions for Teammate asks for docs' })); + await screen.findByRole('menuitem', { name: 'Pin session' }); + expect(screen.queryByRole('menuitem', { name: 'Approve' })).not.toBeInTheDocument(); + expect(screen.queryByRole('menuitem', { name: 'Decline' })).not.toBeInTheDocument(); + }); + + it('offers no approval on a session whose followed card is not waiting', async () => { + const user = userEvent.setup(); + renderSection(); + await screen.findByRole('link', { name: 'Ask for a login fix' }); + + await user.click(screen.getByRole('button', { name: 'Session actions for Ask for a login fix' })); + + await screen.findByRole('menuitem', { name: 'Pin session' }); + expect(screen.queryByRole('menuitem', { name: 'Approve' })).not.toBeInTheDocument(); + }); +}); diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useAnswerParkedApproval.ts b/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useAnswerParkedApproval.ts new file mode 100644 index 00000000000..43617da8114 --- /dev/null +++ b/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useAnswerParkedApproval.ts @@ -0,0 +1,27 @@ +import { toast } from '@mastra/playground-ui/components/Toaster'; +import { useIsMutating, useMutation, useQueryClient } from '@tanstack/react-query'; + +import { useApiConfig } from '../../../../api/config'; +import { queryKeys } from '../../../../api/keys'; +import { answerParkedApproval } from '../services/user-sessions'; + +/** Answers the tool call a followed card's phase session waits on, from the row of the session following it. */ +export function useAnswerParkedApproval(factoryId: string, sessionId: string | undefined) { + const { baseUrl } = useApiConfig(); + const queryClient = useQueryClient(); + const mutationKey = ['answer-parked-approval', sessionId]; + const answering = useIsMutating({ mutationKey }) > 0; + const { mutate } = useMutation({ + mutationKey, + mutationFn: (decision: 'approve' | 'decline') => { + if (!sessionId) throw new Error('Nothing is waiting for approval.'); + return answerParkedApproval(baseUrl, sessionId, decision); + }, + onSuccess: (_, decision) => { + void queryClient.invalidateQueries({ queryKey: queryKeys.workItems(factoryId) }); + toast(decision === 'approve' ? 'Approved' : 'Declined'); + }, + onError: error => toast.error(error instanceof Error ? error.message : 'Failed to answer the approval'), + }); + return { answer: sessionId ? mutate : undefined, answering }; +} diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useSessionListRows.ts b/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useSessionListRows.ts index 3527d7e8f5d..c7758fb6bd5 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useSessionListRows.ts +++ b/mastracode/factory-ui/src/ui/domains/workspaces/hooks/useSessionListRows.ts @@ -9,7 +9,7 @@ import { allSessionRows, useWorkspacesQuery } from '../../../../hooks/useWorkspa import { AGENT_CONTROLLER_ID } from '../../chat/services/constants'; import { itemAwaitsPerson } from '../../factory/boardCardState'; import { useItemDecisions } from '../../factory/hooks/useBoardDecisions'; -import { buildFactorySessionRow, buildUserSessionRow, oneRowPerCard } from '../services/sessionRows'; +import { buildFactorySessionRow, buildUserSessionRow, linkFollowedCards, oneRowPerCard } from '../services/sessionRows'; import type { OneRowPerCardOptions, SessionListRow } from '../services/sessionRows'; import { sessionWorkItemIndex } from '../services/sessionWorkItems'; import { usePinnedSessions } from './usePinnedSessions'; @@ -92,5 +92,11 @@ export function useSessionListRows( }); }); - return { rows: [...oneRowPerCard(factoryRows, catalog.data, options), ...userRows], ...loadState }; + return { + rows: [ + ...oneRowPerCard(factoryRows, catalog.data, options), + ...linkFollowedCards(userRows, factoryRows, parkedSessions, options), + ], + ...loadState, + }; } diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/services/sessionPresentation.ts b/mastracode/factory-ui/src/ui/domains/workspaces/services/sessionPresentation.ts index 0309dde44a5..5ddab59e7da 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/services/sessionPresentation.ts +++ b/mastracode/factory-ui/src/ui/domains/workspaces/services/sessionPresentation.ts @@ -18,13 +18,20 @@ export interface SessionViewerProfile { avatarUrl?: string; } +/** A session the Factory itself owns: automatic work no person started. */ +export function isFactoryOwnedSession(session: Pick): boolean { + return session.userId.startsWith('factory-project:'); +} + export function getSessionOwnerDetails( session: FactoryUserSession, viewer: SessionViewerProfile | undefined, ): SessionOwnerDetails { const isViewer = Boolean(viewer?.userId) && session.userId === viewer?.userId; const name = - (isViewer && (viewer?.name?.trim() || viewer?.email?.trim())) || session.owner?.name?.trim() || session.userId; + (isViewer && (viewer?.name?.trim() || viewer?.email?.trim())) || + session.owner?.name?.trim() || + (isFactoryOwnedSession(session) ? 'Factory' : session.userId); const avatarUrl = (isViewer && viewer?.avatarUrl?.trim()) || session.owner?.avatarUrl?.trim(); return { name, diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/services/sessionRows.ts b/mastracode/factory-ui/src/ui/domains/workspaces/services/sessionRows.ts index 71598597fd3..0227054897b 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/services/sessionRows.ts +++ b/mastracode/factory-ui/src/ui/domains/workspaces/services/sessionRows.ts @@ -13,7 +13,12 @@ import type { PullRequestStatus } from '../../factory/boardItems'; import { itemBoard } from '../../factory/boardStages'; import type { ChangeRequestProvider } from '../../factory/services/githubSubscriptions'; import type { WorkItem, WorkItemSource } from '../../factory/services/workItems'; -import { getFactorySessionSource, getSessionOwnerDetails, getUserSessionLabel } from './sessionPresentation'; +import { + getFactorySessionSource, + getSessionOwnerDetails, + getUserSessionLabel, + isFactoryOwnedSession, +} from './sessionPresentation'; import type { SessionOwnerDetails, SessionSource, SessionViewerProfile } from './sessionPresentation'; import { sessionRowStatus } from './sessionStatus'; import type { SessionRowStatus } from './sessionStatus'; @@ -90,6 +95,10 @@ export interface SessionListRow { cardStatus?: SessionActivityStatus; /** What a child row is named in the sidebar: the phase its session ran in. */ phaseLabel?: string; + /** Listed under a person's session, but the Factory owns and runs it. */ + runByFactory?: boolean; + /** A followed card's phase session that waits on a person, answerable from this row. */ + waitingSessionId?: string; createdAt: string; updatedAt: string; } @@ -265,6 +274,50 @@ function orderCardRows( .map((row, index) => (index === 0 ? row : { ...row, phaseLabel: phaseLabel(row) })); } +/** + * Ties each session to the phase sessions of the cards it follows. Those sessions stay the + * card's: the row links to them and lists them under itself when child sessions are revealed. + * While one is parked the row reads "waiting on you", but only for a viewer who can answer: + * the row is their session, or a session of theirs follows the same card. + */ +export function linkFollowedCards( + rows: readonly SessionListRow[], + cardRows: readonly SessionListRow[], + parkedSessions: ReadonlySet, + { revealChildSessions = false }: OneRowPerCardOptions = {}, +): SessionListRow[] { + const viewerFollows = new Set( + rows.flatMap(row => (row.ownedByViewer ? (row.session.followedWorkItemIds ?? []) : [])), + ); + const waitsOnViewer = (cardRow: SessionListRow) => + parkedSessions.has(cardRow.session.sessionId) && cardRow.itemId !== undefined && viewerFollows.has(cardRow.itemId); + return rows.map(row => { + const followed = new Set(row.session.followedWorkItemIds); + if (followed.size === 0) return row; + const linked = cardRows.filter( + cardRow => + cardRow.itemId !== undefined && + followed.has(cardRow.itemId) && + cardRow.session.sessionId !== row.session.sessionId, + ); + if (linked.length === 0) return row; + const waiting = linked.find(waitsOnViewer); + return { + ...row, + ...(waiting ? { status: 'waiting' as const, waitingSessionId: waiting.session.sessionId } : {}), + ...(revealChildSessions + ? { + childRows: linked.map(cardRow => ({ + ...cardRow, + ...(waitsOnViewer(cardRow) ? { waitingSessionId: cardRow.session.sessionId } : {}), + ...(isFactoryOwnedSession(cardRow.session) ? { runByFactory: true } : {}), + })), + } + : {}), + }; + }); +} + export interface OneRowPerCardOptions { /** List the card's other sessions under its row instead of folding them into it. */ revealChildSessions?: boolean; diff --git a/mastracode/factory-ui/src/ui/domains/workspaces/services/user-sessions.ts b/mastracode/factory-ui/src/ui/domains/workspaces/services/user-sessions.ts index 5dea75c25d9..5ba06e7e11f 100644 --- a/mastracode/factory-ui/src/ui/domains/workspaces/services/user-sessions.ts +++ b/mastracode/factory-ui/src/ui/domains/workspaces/services/user-sessions.ts @@ -39,6 +39,8 @@ export interface FactoryUserSession { updatedAt: string; /** What the viewer may do with this session, computed by the server. */ capabilities?: { recreateSandbox: boolean; takeOwnership: boolean; switchModel?: boolean }; + /** The cards this session follows: the ones it asked for or subscribed to. Only the list read reports it. */ + followedWorkItemIds?: readonly string[]; } type FactoryUserSessionPayload = Omit & { title?: string | null }; @@ -158,6 +160,24 @@ export async function regenerateSessionTitle(baseUrl: string, sessionId: string) return body.title; } +/** Approve or decline the tool call a card's phase session waits on. Its owner, an admin, or anyone following the card may. */ +export async function answerParkedApproval( + baseUrl: string, + sessionId: string, + decision: 'approve' | 'decline', + toolCallId?: string, +): Promise { + const res = await fetch(`${baseUrl}/web/user-sessions/${encodeURIComponent(sessionId)}/parked-approval`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + credentials: 'include', + body: JSON.stringify({ decision, ...(toolCallId ? { toolCallId } : {}) }), + }); + if (res.ok) return; + const body: { error?: string } = await res.json().catch(() => ({})); + throw new Error(body.error ?? `Failed to answer the approval (${res.status})`); +} + export type UserSessionVisibility = FactoryUserSession['visibility']; /** Owner-only: share a session with the organization or make it private again. */ diff --git a/mastracode/factory-ui/src/ui/pages/__tests__/ThreadPageTeammateSession.msw.test.tsx b/mastracode/factory-ui/src/ui/pages/__tests__/ThreadPageTeammateSession.msw.test.tsx index da630733b88..7d90f5483df 100644 --- a/mastracode/factory-ui/src/ui/pages/__tests__/ThreadPageTeammateSession.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/pages/__tests__/ThreadPageTeammateSession.msw.test.tsx @@ -190,6 +190,23 @@ describe("a teammate's Factory session", () => { expect(screen.queryByText(/user-ward/)).not.toBeInTheDocument(); }); + // A card a webhook filed, or an automatic phase picked up, runs in a session no person owns. + it('says the session is the Factory’s, with no takeover, when automatic work owns it', async () => { + openWardSessionAs('user-caleb', { + session: { + ...wardSession, + userId: `factory-project:${FACTORY_ID}`, + owner: { id: `factory-project:${FACTORY_ID}`, name: 'Factory' }, + branch: 'factory/issue-49', + capabilities: { ...wardSession.capabilities, takeOwnership: false }, + }, + path: BOARD_THREAD_PATH, + }); + + expect(await screen.findByText('You’re steering the Factory’s session')).toBeInTheDocument(); + expect(screen.queryByRole('button', { name: 'Take ownership' })).not.toBeInTheDocument(); + }); + it('offers no takeover of a Slack thread, which the server keeps with its owner', async () => { openWardSessionAs('user-damien', { session: { diff --git a/mastracode/factory/README.md b/mastracode/factory/README.md index 4d4497da52c..803898800b5 100644 --- a/mastracode/factory/README.md +++ b/mastracode/factory/README.md @@ -622,7 +622,7 @@ Boards and phases take `name` and an optional `description`. A phase lists the p - `runner` — `{ agentId?, skill?, context?, instructions?, goal? }`. The runner is the only way a phase starts work: when a card enters the phase, from any source and including a card filed straight into it, Factory starts `skill` in the `context` session. `context` names the session the phase runs in (defaults to `work`); phases that share a context share a session. When the agent moves its own card into another phase of its context, that phase's `skill` still starts: its kickoff is queued onto the agent's run. Moving a card back into the phase it is in (a re-entry, such as a re-review after a push) supersedes the run in flight and resumes the skill. `skill` names a built-in Factory skill or one of your app's skills (see [Skills for custom boards](#skills-for-custom-boards)); a phase without one starts nothing. The kickoff names the card only by its URL (or title, quoted as untrusted data when an outside author wrote it); the agent reads everything else from the [`factory-work-item` signal](#the-factory-work-item-signal). `instructions` (up to 1,000 characters) are added to the kickoff. `agentId` defaults to `code-agent`, the only agent Factory runs today. - `runner.goal` — `{ objective, maxRuns? }`: the run pursues `objective` (up to 2,000 characters) as a Mastra goal. Factory stores it on the session's thread as the run starts, with the session's model as judge, and after each run the judge decides from the objective text and the latest messages whether the work is done, should continue (Factory starts another run, up to `maxRuns`, 1–50) or is waiting for a person. Waiting leaves the goal active and the card in its phase; the next message a person sends resumes it, and a skill asks people with `ask_user`, which parks the run in Factory's attention view. When `maxRuns` runs out, the goal pauses and the card stays: resume it from the session or move the card. When the card leaves the phase, by anyone, Factory marks the goal done. The judge sees only the objective and the latest messages, so state the done and waiting criteria in the objective. Work's Building pursues the approved plan this way, with up to 20 runs. - `autoStart` and `autoStartWhen` — the phase's runs start without a person's approval, for every card or only for cards matching the rule. To start only trusted authors' cards, add `author.trusted equals true` to `autoStartWhen`; by default, [intake routes](#intake-routes) file GitHub and GitLab cards from outside the write-access circle in Work › Intake, where nothing starts on its own. -- `exitTool` — a tool name, or `{ id, autoApprove, autoApproveWhen }`, that ends the phase. The phase holds the card until that tool succeeds (for `submit_plan`, with an approved plan) in the session that works the card there: until then an agent or board rule asking to move the card on to another working phase is rejected with `approval_required`. Once it has succeeded during the card's current visit to the phase, the agent moves the card itself with `factory_transition_work_item` (the factory-phase signal tells it so and lists `nextPhases`), or a board tool rule for the exit tool (`tools`) moves it; the tool's success never moves the card by itself. A person can move the card at any time. The phase needs at least one next phase. `autoApprove` and `autoApproveWhen` only decide whether the tool approves itself, for every card or only cards matching the rule, or waits for a person; they are the only way plans are approved without a person. Factory sessions already run tools without asking, so for `submit_plan` this means an auto-approved plan is accepted without a person. Work's Planning declares `{ id: 'submit_plan', autoApprove: false }`: every plan waits for a person, who approves `submit_plan` in a signed-in chat (or moves the card), and then `factory-plan` moves the card to Building. +- `exitTool` — a tool name, or `{ id, autoApprove, autoApproveWhen }`, that ends the phase. The phase holds the card until that tool succeeds (for `submit_plan`, with an approved plan) in the session that works the card there: until then an agent or board rule asking to move the card on to another working phase is rejected with `approval_required`. Once it has succeeded during the card's current visit to the phase, the agent moves the card itself with `factory_transition_work_item` (the factory-phase signal tells it so and lists `nextPhases`), or a board tool rule for the exit tool (`tools`) moves it; the tool's success never moves the card by itself. A person can move the card at any time. The phase needs at least one next phase. `autoApprove` and `autoApproveWhen` only decide whether the tool approves itself, for every card or only cards matching the rule, or waits for a person; they are the only way plans are approved without a person. Factory sessions already run tools without asking, so for `submit_plan` this means an auto-approved plan is accepted without a person. Any other exit tool that pauses for a yes or no is approved the same way, and the sessions following the card are told a run waits on them only when a person has to answer. Work's Planning declares `{ id: 'submit_plan', autoApprove: false }`: every plan waits for a person, who approves `submit_plan` in a signed-in chat (or moves the card), and then `factory-plan` moves the card to Building. - `tools` — Factory tools the phase gives the session that works the card in it (the session whose context is the phase's `runner.context`): `factory_record_review_verdict` and `factory_review_source`. Tools follow the card: when it moves to a phase without them, the session loses them on its next turn, and a verdict tool call made after the card moved is refused. Every bound session keeps `factory_transition_work_item`. Work's Review grants both; a self-review phase, on a board that has one, grants only the verdict tool. Rules test a card's facts, read from its work item as the provider reported it: @@ -1284,7 +1284,7 @@ Read tools and `factory_message_origin` are available on every turn. The other t `factory_switch_session_model` changes the model of a side, work item or review session you own in the same Factory, without recreating it. It refuses a model this server can't run. A running session switches right away; a stopped one uses the model on its next run. -`factory_create_work_item` files the card as the caller where the project's [intake routes](#intake-routes) send it, or in the Work board's first phase when no route matches (a project without Work: its first board's), stores the description that its runs start from, and subscribes the session. Name the `repository` when the Factory links more than one: a run can't start on a card that doesn't say which. `factory_update_work_item` sets it afterwards, like choosing a repository on the card, and also edits the title, the description and the parent item. It can't pre-approve plans: a plan waits for a person unless the board's phase auto-approves it. Both refuse a repository the Factory doesn't link, and a card synced from an issue keeps the issue's repository. Stages, the board and role sessions aren't fields it edits; stages move with `factory_transition_work_item`. Subscriptions are stored per work item and session in the `factory_work_item_subscriptions` collection and are removed with the item, so any number of sessions can follow one item. +`factory_create_work_item` files the card as the caller where the project's [intake routes](#intake-routes) send it, or in the Work board's first phase when no route matches (a project without Work: its first board's), stores the description that its runs start from, and subscribes the session. Name the `repository` when the Factory links more than one: a run can't start on a card that doesn't say which. `factory_update_work_item` sets it afterwards, like choosing a repository on the card, and also edits the title, the description and the parent item. It can't pre-approve plans: a plan waits for a person unless the board's phase auto-approves it. Both refuse a repository the Factory doesn't link, and a card synced from an issue keeps the issue's repository. Stages, the board and role sessions aren't fields it edits; stages move with `factory_transition_work_item`. A session that moves a card follows it from then on, so it hears from the run the move starts. Subscriptions are stored per work item and session in the `factory_work_item_subscriptions` collection and are removed with the item, so any number of sessions can follow one item. #### Messaging between sessions @@ -1301,7 +1301,7 @@ How a message is delivered depends on its priority. `urgent` always delivers, ev - **Side session** (no `workItem`): a standalone session with no work item, for a one-off job. It uses the same repository as the session that started it. Factory stores that session on the new session's row (`origin_session_id`, `origin_thread_id`) and copies the parent's visibility. It runs on the model of the session that started it, or on `model` when one is passed. That model has to be one the session's credentials can run; an unknown or unrunnable model is refused before anything is created. When the parent has no model set, the side session keeps the Factory's default worker model. - **Work-item role** (`workItem` and `role`): starts a role the item's board seats, the same way **Start** does in the Factory UI. The card does not move and no autonomy is armed. The tool refuses when the role already has a session, naming it so the agent can message it instead, and refuses an item linked to several repositories. The caller is subscribed to the item, and the run is recorded as `factory.run.started` with the caller as the person who started it. -Both modes attribute the new session to the caller, so it runs with the caller's credentials (the caller's own keys under the `user` model scope, the organization's under `factory`). A work-item role keeps the Factory's default worker model. The first message runs with only the caller as its user, never the rest of the parent turn's context. The tool needs no approval but, like the other management tools, only appears on turns a signed-in person started. +A side session belongs to the caller and runs with the caller's credentials. A work-item role belongs to the caller only in a Factory on the `user` model scope. Where card work runs on the organization's keys (`factory` and `hybrid`), the role's session belongs to the Factory itself, as every phase session there does, whoever started or moved the card: the person is recorded as the one who started it, and their session follows the card so it hears when that run waits on someone and can approve or decline from there. Without an organization model key the start is refused with a message saying to add one. A work-item role keeps the Factory's default worker model. The first message runs with only the session's owner as its user, never the rest of the parent turn's context. The tool needs no approval but, like the other management tools, only appears on turns a signed-in person started. #### Reports @@ -1319,7 +1319,7 @@ Progress reports from one session replace each other while unread. `done`, `fail Every run of a work session or side session ends with exactly one final report, however the run started: the board, a person typing into the session, a wake from another session's message, or a run after a server restart. Each Factory session gets a listener when it is created. A session with an active run binding reports to everyone following its work item, including for the run that moved the item to a finished stage and so ended its own binding; a side session reports to the session that started it; a person's own session reports to nobody. When a run ends, Factory checks each recipient's thread for a final report the agent sent since the run started, and sends one itself to the recipients that lack it: `done` when the run completed, `failed` when it ended in error (quoting the error), and `blocked`, naming the tool, when the run stopped waiting for an answer or for someone to approve a tool call. A reply with a final `status` counts as the final report, and any reply counts for a completed run. A run that completes after the agent reported `blocked` is waiting for an answer, so it gets no `done`; a run someone stopped gets no report. A board run that fails before it ever runs (no session, a configuration the run can't succeed with) reports `failed` once no retry remains. These backstop reports carry a `backstop` attribute. -A run that holds a tool call for approval stays open, so the same listener tells those sessions right away: an urgent `approval` notification names the session, the tool, its arguments and the `toolCallId`, once per call. A session that follows the work item, or started the side session, can answer it with `factory_answer_approval`, as the person signed in to it; the answer is audited as `factory.run.approved` or `factory.run.dismissed`. Other people's private sessions can't be answered, and an approval whose run already ended can't be either: the tool says so, and the session can be messaged to try again. +A run that holds a tool call for approval stays open, so the same listener tells those sessions right away: an urgent `approval` notification names the session, the tool, its arguments and the `toolCallId`, once per call. A session that follows the work item, or started the side session, can answer it with `factory_answer_approval`, as the person signed in to it; the answer is audited as `factory.run.approved` or `factory.run.dismissed`. A tool that pauses itself for a bare yes or no, such as `submit_plan`, ends the run instead: the `blocked` report then names the session and the `toolCallId` to approve or decline the same way, while a tool that needs a typed answer is answered in its session. Whoever answers, the run carries on as the session's owner. Other people's private sessions can't be answered, and an approval whose run already ended can't be either: the tool says so, and the session can be messaged to try again. When a followed work item changes stage, subscribers whose session is running get a `low` priority `stage` notice. A stage change never wakes an offline session; it sees the current stage in its state signal instead. diff --git a/mastracode/factory/package.json b/mastracode/factory/package.json index 41dde1b69f7..860bd428013 100644 --- a/mastracode/factory/package.json +++ b/mastracode/factory/package.json @@ -77,6 +77,7 @@ "zod": "catalog:" }, "devDependencies": { + "@copilotkit/aimock": "^1.46.0", "@internal/lint": "workspace:*", "@internal/types-builder": "workspace:*", "@internal/workspace": "workspace:*", diff --git a/mastracode/factory/src/factory.ts b/mastracode/factory/src/factory.ts index 893cf20a364..17832fd4aa5 100644 --- a/mastracode/factory/src/factory.ts +++ b/mastracode/factory/src/factory.ts @@ -2341,6 +2341,7 @@ export class MastraFactory { threadId: session.thread.getId(), ...request, }), + answersItself: toolCallId => this.#dispatcher?.autoApproves(toolCallId) ?? false, }, ); observeSessionThreadStamp(session); diff --git a/mastracode/factory/src/integrations/github/routes.ts b/mastracode/factory/src/integrations/github/routes.ts index 94759026765..a4d1dfbffe0 100644 --- a/mastracode/factory/src/integrations/github/routes.ts +++ b/mastracode/factory/src/integrations/github/routes.ts @@ -34,6 +34,7 @@ import { normalizeSessionTitle } from '../../session/session-title.js'; import type { StateSigner } from '../../state-signing.js'; import type { AuditEmitter } from '../../storage/domains/audit/domain.js'; import type { MemorySettingsStorage } from '../../storage/domains/memory-settings/base.js'; +import { isFactoryPrincipalId } from '../../storage/domains/projects/base.js'; import type { FactoryProjectsStorage } from '../../storage/domains/projects/base.js'; import type { ProjectRepository, @@ -1185,10 +1186,16 @@ function createSessionOwnerProfileResolver(users: SessionOwnerUserProvider | und }; return async (userIds: string[]): Promise> => { - if (!users) return new Map(); - - const requestedUserIds = [...new Set(userIds)].slice(0, MAX_SESSION_OWNER_PROFILES); const profiles = new Map(); + // A session the Factory owns has no person to look up; it is named for what it is. + for (const userId of userIds) { + if (isFactoryPrincipalId(userId)) profiles.set(userId, { id: userId, name: 'Factory' }); + } + if (!users) return profiles; + + const requestedUserIds = [...new Set(userIds)] + .filter(userId => !isFactoryPrincipalId(userId)) + .slice(0, MAX_SESSION_OWNER_PROFILES); const unresolvedUserIds: string[] = []; const now = Date.now(); diff --git a/mastracode/factory/src/routes/source-control-sessions.ts b/mastracode/factory/src/routes/source-control-sessions.ts index 5e5fdaab211..1ee6c5b8492 100644 --- a/mastracode/factory/src/routes/source-control-sessions.ts +++ b/mastracode/factory/src/routes/source-control-sessions.ts @@ -6,6 +6,7 @@ import { registerApiRoute } from '@mastra/core/server'; import { createSignal } from '@mastra/core/signals'; import { UniqueViolationError } from '@mastra/core/storage'; import type { Context } from 'hono'; +import { z } from 'zod'; import { reclaimDeletedSessionSandbox } from '../integrations/github/sandbox-release.js'; import { isValidGitRef } from '../sandbox/git-ref.js'; @@ -25,6 +26,7 @@ import { SESSION_OWNER_SIGNAL_TAG } from '../session-owner-signal.js'; import type { AuditRecorder } from '../storage/domains/audit/domain.js'; import type { FilesystemStorage } from '../storage/domains/filesystem/base.js'; import type { MemorySettingsStorage } from '../storage/domains/memory-settings/base.js'; +import { isFactoryPrincipalId } from '../storage/domains/projects/base.js'; import type { FactoryProjectsStorage } from '../storage/domains/projects/base.js'; import type { ProjectRepository, @@ -32,6 +34,7 @@ import type { SourceControlStorageHandle, } from '../storage/domains/source-control/base.js'; import type { WorkItemsStorage } from '../storage/domains/work-items/base.js'; +import { answerParkedCall } from '../tools/approval-tools.js'; import { loose } from './route.js'; import type { RouteAuth } from './route.js'; import { canReadSessionResource, canSwitchSessionModel, canViewSourceControlSession } from './session-access.js'; @@ -69,7 +72,13 @@ export interface SourceControlSessionRoutesOptions { filesystem?: Pick; /** How long recreate waits for an aborted run to settle before destroying. */ abortSettleTimeoutMs?: number; - workItems?: Pick; + workItems?: Pick & + Partial< + Pick< + WorkItemsStorage, + 'listProjectSubscriptions' | 'listWorkItemSubscribers' | 'findActiveRunBindingForSession' | 'get' + > + >; /** Moves a thread, with everything keyed by its resource, when a session's visibility changes. */ moveThread?: (input: { threadId: string; resourceId: string }) => Promise; } @@ -97,6 +106,34 @@ async function sessionManagePermission( return (await auth.isOrganizationAdmin(c, session.orgId)) ? 'allowed' : 'forbidden'; } +const parkedApprovalAnswerSchema = z + .object({ + decision: z.enum(['approve', 'decline']), + reason: z.string().trim().min(1).max(1000).optional(), + toolCallId: z.string().trim().min(1).max(200).optional(), + }) + .strict(); + +/** Whether the viewer asked for the card's work: they filed it, or a session of theirs follows it. */ +async function followsCard( + options: SourceControlSessionRoutesOptions, + workItemId: string | undefined, + tenant: { orgId: string; userId: string }, +): Promise { + const workItems = options.workItems; + if (!workItemId || !workItems?.get || !workItems.listWorkItemSubscribers) return false; + const item = await workItems.get({ orgId: tenant.orgId, id: workItemId }); + if (!item) return false; + if (item.createdBy === tenant.userId) return true; + // A follow belongs to its session, and a session can change hands: ask who owns it now. + const followers = await workItems.listWorkItemSubscribers({ orgId: tenant.orgId, workItemId }); + for (const sessionId of new Set(followers.map(follower => follower.sessionId))) { + const following = (await resolveSession(options.sourceControls, sessionId))?.session; + if (following?.orgId === tenant.orgId && following.userId === tenant.userId) return true; + } + return false; +} + function canRecreateSandbox(options: SourceControlSessionRoutesOptions): boolean { return Boolean(options.sessionRetirement) && options.sandboxRecreateSupported === true; } @@ -338,9 +375,15 @@ function createSessionOwnerProfileResolver(users: SessionOwnerUserProvider | und }; return async (userIds: string[]): Promise> => { - if (!users) return new Map(); - const requestedUserIds = [...new Set(userIds)].slice(0, MAX_SESSION_OWNER_PROFILES); const profiles = new Map(); + // A session the Factory owns has no person to look up; it is named for what it is. + for (const userId of userIds) { + if (isFactoryPrincipalId(userId)) profiles.set(userId, { id: userId, name: 'Factory' }); + } + if (!users) return profiles; + const requestedUserIds = [...new Set(userIds)] + .filter(userId => !isFactoryPrincipalId(userId)) + .slice(0, MAX_SESSION_OWNER_PROFILES); const unresolvedUserIds: string[] = []; const now = Date.now(); @@ -554,7 +597,90 @@ export function buildSourceControlSessionRoutes(options: SourceControlSessionRou ) ).flat(); const owners = await resolveOwnerProfiles(sessions.map(session => session.userId)); - return c.json({ sessions: sessions.map(session => withOwnerProfile(session, owners)) }); + // The follow link is the only tie between a person's session and a card's phase sessions. + const followed = new Map(); + for (const link of (await options.workItems?.listProjectSubscriptions?.({ + orgId, + factoryProjectId: project.id, + })) ?? []) { + const workItemIds = followed.get(link.sessionId); + if (workItemIds) workItemIds.push(link.workItemId); + else followed.set(link.sessionId, [link.workItemId]); + } + return c.json({ + sessions: sessions.map(session => ({ + ...withOwnerProfile(session, owners), + followedWorkItemIds: followed.get(session.sessionId) ?? [], + })), + }); + }, + }), + // Approve or decline the tool call a card's phase session waits on, from the card or a + // session following it. The session's owner and org admins may; so may the person who + // filed the card and anyone whose session follows it. The run carries on as its owner. + registerApiRoute('/web/user-sessions/:sessionId/parked-approval', { + method: 'POST', + requiresAuth: false, + handler: async c => { + const resolved = await resolveOrgTenant(loose(c), options.auth); + if ('response' in resolved) return resolved.response; + const body = parkedApprovalAnswerSchema.safeParse(await c.req.json().catch(() => null)); + if (!body.success) { + return c.json( + { error: 'Send a decision of "approve" or "decline", and optionally a reason and toolCallId.' }, + 400, + ); + } + const match = await resolveSession(options.sourceControls, c.req.param('sessionId')); + const session = match?.session; + if (!session) return c.json({ error: 'Session not found' }, 404); + const permission = await sessionManagePermission(loose(c), options.auth, resolved.tenant, session); + if (permission === 'not-found') return c.json({ error: 'Session not found' }, 404); + const binding = + session.factoryProjectId && options.workItems?.findActiveRunBindingForSession + ? await options.workItems.findActiveRunBindingForSession({ + orgId: session.orgId, + factoryProjectId: session.factoryProjectId, + sessionId: session.sessionId, + }) + : null; + if (permission !== 'allowed' && !(await followsCard(options, binding?.workItemId, resolved.tenant))) { + return c.json( + { error: "Only the session's owner, an organization admin, or someone following its card can answer." }, + 403, + ); + } + const controller = options.controller; + if (!controller) return c.json({ error: 'Sessions are not available on this server.' }, 503); + const { decision, reason } = body.data; + let answered: { toolCallId: string; toolName: string }; + try { + answered = await answerParkedCall( + { messaging: async () => ({ controller }) as never }, + { + session, + ...(body.data.toolCallId ? { toolCallId: body.data.toolCallId } : {}), + decision, + declineReason: reason ?? 'Declined from the card.', + }, + ); + } catch (error) { + return c.json({ error: error instanceof Error ? error.message : String(error) }, 409); + } + const { toolCallId, toolName } = answered; + await options.audit?.record({ + orgId: session.orgId, + actorId: resolved.tenant.userId, + actorType: 'human', + action: decision === 'approve' ? 'factory.run.approved' : 'factory.run.dismissed', + ...(session.factoryProjectId ? { factoryProjectId: session.factoryProjectId } : {}), + targets: [ + { type: 'session', id: session.sessionId }, + ...(binding ? [{ type: 'work_item' as const, id: binding.workItemId }] : []), + ], + metadata: { toolCallId, toolName, sessionId: session.sessionId, decision, cause: 'web' }, + }); + return c.json({ answered: decision, sessionId: session.sessionId, toolCallId, toolName }); }, }), ...projectSessionRoutes('/web/source-control/projects/:id/sessions', options, resolveOwnerProfiles), diff --git a/mastracode/factory/src/routes/surface.test.ts b/mastracode/factory/src/routes/surface.test.ts index 424aee2c542..f2dc8f0d4dd 100644 --- a/mastracode/factory/src/routes/surface.test.ts +++ b/mastracode/factory/src/routes/surface.test.ts @@ -10,10 +10,19 @@ import { FactoryTransitionService } from '../rules/transition-service.js'; import { createFactoryStorageForTests, createProviderWorkItemForTests } from '../storage/test-utils.js'; import { prepareFactoryRuleBinding } from './surface.js'; -async function seedFactoryWithRepository(options?: { defaultModelId?: string; modelScope?: 'factory' | 'user' }) { +async function seedFactoryWithRepository(options?: { + defaultModelId?: string; + modelScope?: 'factory' | 'user' | 'hybrid'; + /** Who set the Factory up; the repository is always connected by `user-1`. */ + createdBy?: string; +}) { const seeded = await createFactoryStorageForTests(); const sourceControl = seeded.sourceControl.forIntegration('github'); - const project = await seeded.projects.create({ orgId: 'org-1', userId: 'user-1', input: { name: 'Mastra' } }); + const project = await seeded.projects.create({ + orgId: 'org-1', + userId: options?.createdBy ?? 'user-1', + input: { name: 'Mastra' }, + }); if (options?.defaultModelId || options?.modelScope) { await seeded.projects.update({ orgId: 'org-1', @@ -171,9 +180,10 @@ describe('prepareFactoryRuleBinding', () => { ); const { sessionId, userId } = prepare.mock.calls[0]![0] as unknown as { sessionId: string; userId: string }; - expect(userId).toBe('user-1'); + // Nobody started this run, so the session is the Factory's own. + expect(userId).toBe(`factory-project:${project.id}`); await expect(sourceControl.sessions.getBySessionId(sessionId)).resolves.toEqual( - expect.objectContaining({ branch: 'factory/issue-49-item1', baseBranch: 'main', userId: 'user-1' }), + expect.objectContaining({ branch: 'factory/issue-49-item1', baseBranch: 'main', userId }), ); }); @@ -232,25 +242,268 @@ describe('prepareFactoryRuleBinding', () => { ); }); - it("keeps a run an agent pre-approved on the repo connector, never on the agent's id", async () => { - const { seeded, sourceControl, project, github } = await seedFactoryWithRepository(); - const prepare = vi.fn(async () => ({}) as never); - const input = bindingInput(project.id); - (input.record as { approvedBy?: string | null }).approvedBy = 'agent:binding-1'; + describe('who owns a new phase session', () => { + type Seed = Awaited>; - await prepareFactoryRuleBinding( - github, - { prepare } as unknown as FactoryStartCoordinator, - seeded.projects, - boards, - input, - ); + function start(seed: Seed, approvedBy: string | undefined) { + const prepare = vi.fn(async () => ({}) as never); + const input = bindingInput(seed.project.id); + if (approvedBy) (input.record as { approvedBy?: string | null }).approvedBy = approvedBy; + const started = prepareFactoryRuleBinding( + seed.github, + { prepare } as unknown as FactoryStartCoordinator, + seed.seeded.projects, + boards, + input, + undefined, + { + workItems: seed.seeded.workItems, + modelCredentials: seed.seeded.credentials, + customProviders: seed.seeded.customProviders, + }, + ); + return { prepare, started }; + } - const { sessionId, userId } = prepare.mock.calls[0]![0] as unknown as { sessionId: string; userId: string }; - expect(userId).toBe('user-1'); - await expect(sourceControl.sessions.getBySessionId(sessionId)).resolves.toEqual( - expect.objectContaining({ userId: 'user-1' }), - ); + async function ownerOfPreparedSession(seed: Seed, approvedBy: string | undefined) { + const { prepare, started } = start(seed, approvedBy); + await started; + const { sessionId, userId } = prepare.mock.calls[0]![0] as unknown as { sessionId: string; userId: string }; + const row = await seed.sourceControl.sessions.getBySessionId(sessionId); + expect(row?.userId).toBe(userId); + return userId; + } + + async function sessionOf(seed: Seed, userId: string) { + return seed.sourceControl.sessions.create({ + sessionId: crypto.randomUUID(), + projectRepositoryId: seed.projectRepository.id, + factoryProjectId: seed.project.id, + orgId: 'org-1', + userId, + branch: `sessions/${userId}`, + baseBranch: 'main', + visibility: 'org', + }); + } + + function addOrganizationKey(seed: Seed) { + return seed.seeded.credentials.setCredential({ orgId: 'org-1' }, 'openai', { type: 'api_key', key: 'sk-org' }); + } + + /** A phase run of a card `requester-1` asked for, whose agent then moves the card on. */ + async function phaseRunOf(seed: Seed) { + const triage = await sessionOf(seed, 'requester-1'); + const { binding } = await seed.seeded.workItems.prepareRunStart({ + orgId: 'org-1', + userId: 'requester-1', + factoryProjectId: seed.project.id, + workItem: { + input: { + board: 'work', + externalSource: { integrationId: 'github', type: 'issue', externalId: '49' }, + title: 'Broken login', + stages: ['triage'], + sessions: {}, + metadata: {}, + }, + }, + role: 'triage', + session: { sessionId: triage.sessionId, branch: triage.branch, threadId: triage.sessionId }, + resourceId: triage.sessionId, + kickoffKey: 'kickoff-1', + kickoffMessage: null, + }); + return binding; + } + + // Whoever moves the card, its phases run on the Factory's model and the organization's keys. + describe.each(['factory', 'hybrid'] as const)('in a Factory on %s credentials', modelScope => { + async function seedWithKey() { + const seed = await seedFactoryWithRepository({ + createdBy: 'factory-creator', + modelScope, + defaultModelId: 'openai/gpt-5.5', + }); + await addOrganizationKey(seed); + return { seed, factory: `factory-project:${seed.project.id}` }; + } + + it('runs the phase as the Factory, on its model, when a person moves or approves the card', async () => { + const { seed, factory } = await seedWithKey(); + const { prepare, started } = start(seed, 'approver-1'); + + await started; + + expect(prepare).toHaveBeenCalledWith( + expect.objectContaining({ + userId: factory, + // The person stays the one who started it. + startedBy: { type: 'human', id: 'approver-1' }, + modelScope: 'factory', + defaultModelId: 'openai/gpt-5.5', + }), + ); + const { sessionId } = prepare.mock.calls[0]![0] as unknown as { sessionId: string }; + expect(await seed.sourceControl.sessions.getBySessionId(sessionId)).toMatchObject({ userId: factory }); + }); + + it("runs the phase as the Factory when a person's own session moves the card", async () => { + const { seed, factory } = await seedWithKey(); + const chat = await sessionOf(seed, 'requester-1'); + const { prepare, started } = start(seed, `agent:session:${chat.sessionId}`); + + await started; + + expect(prepare).toHaveBeenCalledWith( + expect.objectContaining({ + userId: factory, + // An agent's move is an agent's, never a person's. + startedBy: { type: 'agent', bindingId: `session:${chat.sessionId}`, role: 'session' }, + }), + ); + }); + + it('runs the next phase as the Factory when the agent of an earlier phase moves the card', async () => { + const { seed, factory } = await seedWithKey(); + const binding = await phaseRunOf(seed); + const { prepare, started } = start(seed, `agent:${binding.id}`); + + await started; + + expect(prepare).toHaveBeenCalledWith( + expect.objectContaining({ + userId: factory, + startedBy: { type: 'agent', bindingId: binding.id, role: 'triage' }, + }), + ); + }); + + // A card a webhook filed, or one an automatic phase picked up. + it('runs the phase as the Factory when nobody is behind the move', async () => { + const { seed, factory } = await seedWithKey(); + + await expect(ownerOfPreparedSession(seed, undefined)).resolves.toBe(factory); + }); + + it('starts the phase as the Factory when the organization runs on its own provider and stores no key', async () => { + const seed = await seedFactoryWithRepository({ modelScope }); + await seed.seeded.customProviders.upsert({ + orgId: 'org-1', + userId: 'factory-creator', + input: { + providerId: 'acme', + name: 'Acme', + url: 'https://llm.acme.dev/v1', + apiKey: 'sk-acme', + models: ['fast-1'], + }, + }); + + await expect(ownerOfPreparedSession(seed, 'approver-1')).resolves.toBe(`factory-project:${seed.project.id}`); + }); + + it("does not count another organization's provider as this one's", async () => { + const seed = await seedFactoryWithRepository({ modelScope }); + await seed.seeded.customProviders.upsert({ + orgId: 'org-elsewhere', + userId: 'someone-elsewhere', + input: { + providerId: 'acme', + name: 'Acme', + url: 'https://llm.acme.dev/v1', + apiKey: 'sk-acme', + models: ['fast-1'], + }, + }); + const { prepare, started } = start(seed, 'approver-1'); + + await expect(started).rejects.toMatchObject({ code: 'factory_org_key_missing' }); + expect(prepare).not.toHaveBeenCalled(); + }); + + it.each([ + ['a person moved the card', 'approver-1'], + ['nobody is behind the move', undefined], + ])( + 'says to add an organization key instead of starting a run that cannot reach a model, when %s', + async (_who, approvedBy) => { + const seed = await seedFactoryWithRepository({ createdBy: 'factory-creator', modelScope }); + // Personal keys, the mover's included, are not the Factory's to spend. + for (const userId of ['factory-creator', 'approver-1']) { + await seed.seeded.credentials.setCredential({ orgId: 'org-1', userId }, 'openai', { + type: 'api_key', + key: 'sk-personal', + }); + } + const createSession = vi.spyOn(seed.sourceControl.sessions, 'create'); + const { prepare, started } = start(seed, approvedBy); + + const error = await started.catch((caught: unknown) => caught); + + expect(error).toBeInstanceOf(FactoryDispatchError); + expect(error).toMatchObject({ + code: 'factory_org_key_missing', + message: expect.stringContaining('Add an organization key'), + }); + expect(prepare).not.toHaveBeenCalled(); + expect(createSession).not.toHaveBeenCalled(); + }, + ); + }); + + // A Factory on personal credentials has no keys of its own, so a person has to own the run. + describe('in a Factory on personal credentials', () => { + const seedPersonal = (createdBy = 'factory-creator') => + seedFactoryWithRepository({ createdBy, modelScope: 'user' }); + + it('runs the phase for the person who moved or approved the card', async () => { + const seed = await seedPersonal(); + const { prepare, started } = start(seed, 'approver-1'); + + await started; + + expect(prepare).toHaveBeenCalledWith(expect.objectContaining({ userId: 'approver-1', modelScope: 'user' })); + }); + + it("runs the phase for the person whose own session's agent moved the card", async () => { + const seed = await seedPersonal(); + const chat = await sessionOf(seed, 'requester-1'); + + await expect(ownerOfPreparedSession(seed, `agent:session:${chat.sessionId}`)).resolves.toBe('requester-1'); + }); + + // The triage agent of a card a teammate asked for moves it on to Planning. + it("runs the next phase for the person whose phase session's agent moved the card", async () => { + const seed = await seedPersonal(); + const binding = await phaseRunOf(seed); + + const { prepare, started } = start(seed, `agent:${binding.id}`); + + await started; + + expect(prepare).toHaveBeenCalledWith( + expect.objectContaining({ + userId: 'requester-1', + startedBy: { type: 'agent', bindingId: binding.id, role: 'triage' }, + }), + ); + }); + + it('runs the phase for whoever set the Factory up when nobody is behind the move', async () => { + const seed = await seedPersonal(); + + await expect(ownerOfPreparedSession(seed, undefined)).resolves.toBe('factory-creator'); + const second = await seedPersonal(); + await expect(ownerOfPreparedSession(second, 'agent:binding-that-is-gone')).resolves.toBe('factory-creator'); + }); + + it('falls back to whoever connected the repository only when the Factory names no person', async () => { + const seed = await seedPersonal('system'); + + await expect(ownerOfPreparedSession(seed, undefined)).resolves.toBe('user-1'); + }); + }); }); it('reuses the role session the work item already holds instead of minting a replacement', async () => { @@ -409,7 +662,8 @@ describe('prepareFactoryRuleBinding', () => { }); async function planOwnedSession(branch = 'factory/issue-49') { - const setup = await seedFactoryWithRepository(); + // On personal credentials, where a fresh session belongs to whoever approved the move. + const setup = await seedFactoryWithRepository({ modelScope: 'user' }); const planSession = await setup.sourceControl.sessions.create({ sessionId: 'sess-plan', projectRepositoryId: setup.projectRepository.id, @@ -490,7 +744,9 @@ describe('prepareFactoryRuleBinding', () => { }); it("does not inherit an earlier session on another of the card's repositories", async () => { - const { seeded, sourceControl, project, projectRepository, github } = await seedFactoryWithRepository(); + const { seeded, sourceControl, project, projectRepository, github } = await seedFactoryWithRepository({ + modelScope: 'user', + }); const installation = await sourceControl.installations.upsert({ orgId: 'org-1', connectedByUserId: 'user-1', @@ -533,7 +789,9 @@ describe('prepareFactoryRuleBinding', () => { }); it('mints a fresh session when the held ref no longer resolves to the project', async () => { - const { seeded, sourceControl, project, projectRepository, github } = await seedFactoryWithRepository(); + const { seeded, sourceControl, project, projectRepository, github } = await seedFactoryWithRepository({ + modelScope: 'user', + }); const installation = await sourceControl.installations.upsert({ orgId: 'org-1', connectedByUserId: 'user-1', @@ -590,7 +848,9 @@ describe('prepareFactoryRuleBinding', () => { }); it('mints a fresh session when the held ref lives in another factory project', async () => { - const { seeded, sourceControl, project, projectRepository, github } = await seedFactoryWithRepository(); + const { seeded, sourceControl, project, projectRepository, github } = await seedFactoryWithRepository({ + modelScope: 'user', + }); const otherProject = await seeded.projects.create({ orgId: 'org-1', userId: 'user-1', input: { name: 'Other' } }); const installation = await sourceControl.installations.upsert({ orgId: 'org-1', @@ -652,8 +912,8 @@ describe('prepareFactoryRuleBinding', () => { ); }); - it("attributes an approved decision's run to the approver, not the repo connector", async () => { - const { seeded, sourceControl, project, github } = await seedFactoryWithRepository(); + it("attributes an approved decision's run to the approver, not the repo connector, on personal credentials", async () => { + const { seeded, sourceControl, project, github } = await seedFactoryWithRepository({ modelScope: 'user' }); const prepare = vi.fn(async () => ({}) as never); const input = bindingInput(project.id); @@ -673,8 +933,8 @@ describe('prepareFactoryRuleBinding', () => { ); }); - it("opens a card_action run under the clicker's id", async () => { - const { seeded, sourceControl, project, github } = await seedFactoryWithRepository(); + it("opens a card_action run under the clicker's id on personal credentials", async () => { + const { seeded, sourceControl, project, github } = await seedFactoryWithRepository({ modelScope: 'user' }); const { item } = await seeded.workItems.upsert({ orgId: 'org-1', userId: 'user-1', diff --git a/mastracode/factory/src/routes/surface.ts b/mastracode/factory/src/routes/surface.ts index 18f18c12cb2..6e16ad44f4f 100644 --- a/mastracode/factory/src/routes/surface.ts +++ b/mastracode/factory/src/routes/surface.ts @@ -28,17 +28,20 @@ import type { FactoryBindingPreparationInput } from '../rules/dispatcher.js'; import { FactoryStartCoordinator } from '../rules/start-coordinator.js'; import { FactoryTransitionService } from '../rules/transition-service.js'; import { workItemSource } from '../rules/types.js'; +import type { FactoryRuleActor } from '../rules/types.js'; import { secretKeyMismatchHint, secretKeyProblem } from '../secret-encryption.js'; import { createSourceControlSessionLookup, ensureFactorySourceSession, FactorySourceSessionResolutionError, resolveFactorySourceControl, + requireOrganizationModelKey, } from '../session/factory-session.js'; -import type { EnsuredFactorySourceSession } from '../session/factory-session.js'; +import type { EnsuredFactorySourceSession, OrganizationModelSources } from '../session/factory-session.js'; import type { LiveSessions } from '../session/live-sessions.js'; import { resolveWorkItemRepository } from '../session/work-item-repository.js'; import type { StateSigner } from '../state-signing.js'; +import { isHumanActorId } from '../storage/domains/audit/actors.js'; import type { AuditEmitter, AuditRecorder } from '../storage/domains/audit/domain.js'; import type { StoredBoardsStorage } from '../storage/domains/boards/base.js'; import type { ChannelIdentityStorage } from '../storage/domains/channel-identity/base.js'; @@ -49,8 +52,8 @@ import type { IntakeStorage } from '../storage/domains/intake/base.js'; import type { IntegrationStorage } from '../storage/domains/integrations/base.js'; import type { MemorySettingsStorage } from '../storage/domains/memory-settings/base.js'; import type { ModelDefaultsStorage } from '../storage/domains/model-defaults/base.js'; -import { effectiveModelScope } from '../storage/domains/projects/base.js'; -import type { FactoryProjectsStorage } from '../storage/domains/projects/base.js'; +import { effectiveModelScope, factoryPrincipalId, isFactoryPrincipalId } from '../storage/domains/projects/base.js'; +import type { FactoryProject, FactoryProjectsStorage } from '../storage/domains/projects/base.js'; import type { QueueHealthStorage } from '../storage/domains/queue-health/base.js'; import type { SkillOverridesStorage } from '../storage/domains/skill-overrides/base.js'; import { @@ -60,7 +63,6 @@ import { } from '../storage/domains/source-control/base.js'; import type { SourceControlStorage, SourceControlStorageHandle } from '../storage/domains/source-control/base.js'; import type { VoiceSettingsStorage } from '../storage/domains/voice-settings/base.js'; -import { isAgentActor } from '../storage/domains/work-items/base.js'; import type { FactoryDispatchFailureCode, WorkItemsStorage } from '../storage/domains/work-items/base.js'; import { legacyGithubWorkItemBranch, @@ -321,6 +323,62 @@ function restingExitLane(board: InstalledBoard | undefined, role: string, hasPul return workLaneForRole(board, role) ?? board?.phaseForRole(role); } +/** What the autonomous start reads to decide who a phase session runs as. */ +export interface PhaseSessionOwnerSources extends OrganizationModelSources { + workItems?: Pick; +} + +/** + * Who a newly minted phase session runs as. Wherever runs use the Factory's credentials + * that is the Factory itself, whoever moved the card: the mover is the actor on the move, + * not the owner of the run. A Factory whose runs use personal credentials has no keys of + * its own, so there a person owns the run: whoever moved or approved the card, or the user + * of the session whose agent moved it, else whoever created the Factory. `undefined` + * leaves the last resort to the caller: whoever connected the repository. + */ +async function phaseSessionOwner(args: { + sourceControl: SourceControlStorageHandle; + workItems: Pick | undefined; + project: FactoryProject; + approver: string | undefined; +}): Promise { + const { sourceControl, workItems, project, approver } = args; + if (effectiveModelScope(project.modelScope, 'run') === 'factory') return factoryPrincipalId(project.id); + if (approver?.startsWith('agent:')) { + // `agent:session:` is a person's own session; `agent:` a phase run. + const ref = approver.slice('agent:'.length); + const sessionId = ref.startsWith('session:') + ? ref.slice('session:'.length) + : (await workItems?.findRunBindingById({ orgId: project.orgId, factoryProjectId: project.id, id: ref })) + ?.sessionId; + const session = sessionId ? await sourceControl.sessions.getBySessionId(sessionId) : null; + if (session && session.orgId === project.orgId && isHumanActorId(session.userId)) return session.userId; + } else if (isHumanActorId(approver)) { + return approver; + } + return isHumanActorId(project.createdBy) ? project.createdBy : undefined; +} + +/** + * Who started the work, as the move that starts the run records them. An agent stays an + * agent: recorded as a person, its move would count as a person accepting the work. + */ +async function starterOf( + workItems: Pick | undefined, + project: Pick, + approver: string, +): Promise { + if (!approver.startsWith('agent:')) return { type: 'human', id: approver }; + const bindingId = approver.slice('agent:'.length); + if (bindingId.startsWith('session:')) return { type: 'agent', bindingId, role: 'session' }; + const binding = await workItems?.findRunBindingById({ + orgId: project.orgId, + factoryProjectId: project.id, + id: bindingId, + }); + return { type: 'agent', bindingId, role: binding?.role ?? 'agent' }; +} + /** * Start a factory run for a rule binding: ensure the source-control session the * coordinator requires, then hand it to `prepare` along with the factory's @@ -335,6 +393,7 @@ export async function prepareFactoryRuleBinding( boards: BoardRegistry | ProjectBoardSource, input: FactoryBindingPreparationInput, intake?: Pick, + owner?: PhaseSessionOwnerSources, ): Promise { try { const sourceControl = @@ -426,18 +485,21 @@ export async function prepareFactoryRuleBinding( // The session is filed under the card's repository: the sandbox holds // every environment repository, but the coordinator, the PR tools and the // subscriptions follow the session's link, and the card names which one. + const existingSession = + boundSession ?? (await legacyPlanSession(sourceControl, input, boardId, branch, repository.projectRepositoryId)); + const ownerUserId = + existingSession?.userId ?? + (await phaseSessionOwner({ sourceControl, workItems: owner?.workItems, project, approver })); + if (isFactoryPrincipalId(ownerUserId)) await requireOrganizationModelKey(owner, project); const preparedSession = - boundSession ?? - (await legacyPlanSession(sourceControl, input, boardId, branch, repository.projectRepositoryId)) ?? + existingSession ?? (await ensureFactorySourceSession({ sourceControl, orgId: input.record.orgId, factoryProjectId: input.record.factoryProjectId, projectRepositoryId: repository.projectRepositoryId, branch, - // A person who approved the run is its interactive user: attribute it to - // them, not the repo connector. An agent's pre-approval names no person. - attributeToUserId: isAgentActor(approver) ? undefined : approver, + attributeToUserId: ownerUserId, }).catch(error => { if (error instanceof FactorySourceSessionResolutionError && error.reason === 'repository') { // The card resolved to a linked repository the sandbox will not check out. @@ -466,6 +528,7 @@ export async function prepareFactoryRuleBinding( await coordinator.prepare({ orgId: input.record.orgId, userId: preparedSession.userId, + ...(approver ? { startedBy: await starterOf(owner?.workItems, project, approver) } : {}), factoryProjectId: input.record.factoryProjectId, sessionId: preparedSession.sessionId, modelScope, @@ -857,6 +920,12 @@ export function assembleFactoryApiRoutes(deps: FactoryApiRoutesDeps): ApiRoute[] deps.boardRegistry, input, deps.domains.intake, + { + workItems: deps.domains.workItems, + modelCredentials: deps.domains.modelCredentials, + customProviders: deps.domains.customProviders, + deploymentModelProviders: deps.deploymentModelProviders, + }, ); }, } diff --git a/mastracode/factory/src/rules/dispatch-errors.ts b/mastracode/factory/src/rules/dispatch-errors.ts index 8cf8bb1f1bc..86e13942dee 100644 --- a/mastracode/factory/src/rules/dispatch-errors.ts +++ b/mastracode/factory/src/rules/dispatch-errors.ts @@ -4,7 +4,10 @@ import type { } from '../storage/domains/work-items/base.js'; interface FactoryDispatchFailureMetadata { + /** A person may retry the failed decision. */ canRetry: boolean; + /** `false` when only a person's retry can succeed: the dispatcher does not try again on its own. */ + autoRetry?: false; label: string; } @@ -32,6 +35,13 @@ const FAILURE_METADATA = { run_credentials_unavailable: { canRetry: true, label: 'Model credentials unavailable for the run' }, // The run's request carries no user, so every retry fails the same way; a person has to start it. run_user_unauthenticated: { canRetry: false, label: 'Run started without an authenticated user' }, + // Automatic work runs as the Factory, on the organization's keys only. Trying again cannot add one, + // so the dispatcher stops at once; a person retries after adding the key. + factory_org_key_missing: { + canRetry: true, + autoRetry: false, + label: 'Add an organization model key to run this automatically', + }, run_failed: { canRetry: true, label: 'Agent run ended in error' }, unknown: { canRetry: true, label: 'Factory automation failed' }, // Retired: no path writes these any more, stored rows still read through here. diff --git a/mastracode/factory/src/rules/dispatcher.test.ts b/mastracode/factory/src/rules/dispatcher.test.ts index 3cccede87af..a5445da69b2 100644 --- a/mastracode/factory/src/rules/dispatcher.test.ts +++ b/mastracode/factory/src/rules/dispatcher.test.ts @@ -22,6 +22,7 @@ import { import { BUILD_OBJECTIVE } from '../boards/work.js'; import { publishReviewStatus } from '../integrations/github/review-status.js'; import { DecisionAttentionProvider, failedDecisionAttentionSpec } from '../routes/attention-providers.js'; +import { prepareFactoryRuleBinding } from '../routes/surface.js'; import { resolveFactoryCredentialTenant } from '../session/credential-policy.js'; import { FACTORY_OPEN_RUNS_SETTING, observeSessionRunEnd, waitForSessionRunAudit } from '../session/run-audit.js'; import { FACTORY_RULE_MATERIALIZATION_KEY, WorkItemUpdateConflictError } from '../storage/domains/work-items/base.js'; @@ -29,9 +30,12 @@ import type { WorkItemsStorage } from '../storage/domains/work-items/base.js'; import { Cards } from '../storage/domains/work-items/cards.js'; import { createFactoryStorageForTests, demoteCardsToLegacyForTests } from '../storage/test-utils.js'; import type { FactoryRunEndReporter } from '../tools/reports.js'; +import { observeSessionRunReports } from '../tools/run-watch.js'; +import { retryFactoryDecision } from '../work-items/decision-actions.js'; import { FACTORY_DISPATCH_CONSTANTS, FactoryDecisionDispatcher } from './dispatcher.js'; -import type { FactoryReviewStatusEvent } from './dispatcher.js'; +import type { FactoryBindingPreparationInput, FactoryReviewStatusEvent } from './dispatcher.js'; import { createPhaseGoalEnder, PHASE_GOAL_METADATA_KEY } from './phase-goal.js'; +import type { FactoryStartCoordinator } from './start-coordinator.js'; import { FactoryTransitionService } from './transition-service.js'; import type { FactoryCommitDecision } from './types.js'; @@ -7415,6 +7419,141 @@ describe('run-end backstop report', () => { }); }); +describe('automatic work in a Factory with no organization model key', () => { + it('stops without trying again, then runs as the Factory when a person retries after adding the key', async () => { + const seeded = await createFactoryStorageForTests(); + const storage = seeded.workItems; + const sourceControl = seeded.sourceControl.forIntegration('github'); + const project = await seeded.projects.create({ orgId: 'org-1', userId: 'user-1', input: { name: 'Mastra' } }); + const installation = await sourceControl.installations.upsert({ + orgId: 'org-1', + connectedByUserId: 'user-1', + externalId: '123', + }); + const repository = await sourceControl.repositories.upsert({ + orgId: 'org-1', + input: { installationId: installation.id, externalId: '456', slug: 'mastra-ai/mastra', defaultBranch: 'main' }, + }); + const connection = await sourceControl.connections.create({ + orgId: 'org-1', + factoryProjectId: project.id, + installationId: installation.id, + createdByUserId: 'user-1', + }); + await sourceControl.projectRepositories.link({ + orgId: 'org-1', + connectionId: connection.id, + repositoryId: repository.id, + createdByUserId: 'user-1', + sandboxProvider: 'local', + sandboxWorkdir: '/sandbox/mastra', + }); + const { item } = await storage.upsert({ + orgId: 'org-1', + userId: 'user-1', + factoryProjectId: project.id, + input: { + externalSource: { integrationId: 'github', type: 'issue', externalId: 'github-issue:49' }, + title: 'Broken login', + stages: ['intake'], + sessions: {}, + metadata: { authorTrusted: true, repository: 'mastra-ai/mastra', githubIssueNumber: 49 }, + }, + }); + const boards = createLifecycleTestRegistry(); + const transitionService = new FactoryTransitionService({ storage, configVersion: 'rules-v1', boards }); + await commitDecisions(storage, { + factoryProjectId: project.id, + workItemId: item.id, + stage: 'execute', + decisions: [ + { + type: 'sendMessage', + role: 'plan', + message: 'This work was moved to the planning stage.', + priority: 'urgent', + idleBehavior: 'wake', + prepareBinding: true, + idempotencyKey: 'no-org-key', + }, + ], + ingress: 'move-1', + configVersion: 'rules-v1', + }); + const { controller, session, sendNotificationSignal } = createSession(); + controller.getSession.mockImplementation(async () => session); + // The coordinator's part of a start: seat the run on the session it was handed. + const prepare = vi.fn(async (request: Parameters[0]) => { + const row = await sourceControl.sessions.getBySessionId(request.sessionId); + await storage.prepareRunStart({ + orgId: 'org-1', + userId: request.userId, + factoryProjectId: project.id, + workItem: { + id: item.id, + input: { + externalSource: item.externalSource, + title: item.title, + stages: ['execute'], + sessions: {}, + metadata: item.metadata, + }, + }, + role: 'plan', + session: { sessionId: request.sessionId, branch: row!.branch, threadId: request.sessionId }, + resourceId: project.id, + kickoffKey: 'no-org-key', + kickoffMessage: null, + }); + }); + const dispatcher = new FactoryDecisionDispatcher({ + controller: controller as never, + boards: autoStartingBoards(), + transitionService, + storage, + ownerId: 'worker-1', + prepareBinding: (input: FactoryBindingPreparationInput) => + prepareFactoryRuleBinding( + sourceControl, + { prepare } as unknown as Pick, + seeded.projects, + boards, + input, + undefined, + { workItems: storage, modelCredentials: seeded.credentials }, + ), + }); + const start = Date.parse('2030-01-01T00:00:00Z'); + + await dispatcher.runOnce(new Date(start)); + await dispatcher.runOnce(new Date(start + 2 * 60 * 60_000)); + + const [failed] = await storage.listDeferredDecisions('org-1', project.id); + expect(failed).toMatchObject({ status: 'failed', failureCode: 'factory_org_key_missing', attempts: 1 }); + expect(prepare).not.toHaveBeenCalled(); + + await seeded.credentials.setCredential({ orgId: 'org-1' }, 'openai', { type: 'api_key', key: 'sk-organization' }); + const retried = await retryFactoryDecision({ + workItems: storage, + boards, + orgId: 'org-1', + factoryProjectId: project.id, + decisionId: failed!.id, + }); + expect(retried).toMatchObject({ ok: true }); + await dispatcher.runOnce(new Date(start + 4 * 60 * 60_000)); + + const owner = `factory-project:${project.id}`; + expect(prepare).toHaveBeenCalledWith(expect.objectContaining({ userId: owner })); + expect((await storage.listDeferredDecisions('org-1', project.id))[0]).toMatchObject({ status: 'succeeded' }); + expect((await storage.get({ orgId: 'org-1', id: item.id }))?.sessions.plan).toMatchObject({ startedBy: owner }); + expect(sendNotificationSignal.mock.calls[0]?.[1]?.requestContext?.get('user')).toEqual({ + workosId: owner, + organizationId: 'org-1', + }); + }); +}); + describe('a skill run that ends in error (#27740)', () => { const NO_USER_ERROR = 'Tenant model credential policy could not be resolved: the request has no authenticated user.'; const PROVIDER_401 = Object.assign(new Error('Provider rejected the request'), { statusCode: 401 }); @@ -7850,6 +7989,103 @@ describe('board phase automation', () => { } } }); + + /** What the card's followers are told about the run's pauses, wired as the server wires it. */ + function pausesFollowersHearOf(session: unknown, dispatcher: FactoryDecisionDispatcher) { + const told: Array = []; + observeSessionRunReports( + session as never, + async outcome => { + if (outcome.status === 'blocked') told.push(outcome.toolName); + }, + { answersItself: toolCallId => dispatcher.autoApproves(toolCallId) }, + ); + return told; + } + + // A phase that approves its own exit tool carries on by itself: asking the card's followers to + // approve it sends them to a call that is already answered. + it.each([ + ['submit_plan', { suspendsOnPlan: true }, 'call-plan'], + ['sign_off', { suspendsOnTool: 'sign_off' }, 'call-tool'], + ] as const)( + 'asks nobody to approve %s where the phase approves it itself, and asks where its rule does not match the card', + async (exitTool, parks, toolCallId) => { + const boards = boardsWithBuilding({ + exitTool: { id: exitTool, autoApprove: true, autoApproveWhen: LOW_EFFORT }, + }); + for (const [labels, approvedByItself] of [ + [['effort:low'], true], + [['effort:high'], false], + ] as const) { + const storage = (await createFactoryStorageForTests()).workItems; + const { transitionService } = await queueBuild(storage, [...labels], `notice-${exitTool}-${labels[0]}`); + const { controller, session } = createSession(undefined, parks); + const dispatcher = new FactoryDecisionDispatcher({ + controller: controller as never, + transitionService, + storage, + boards: autoStartingBoards(boards), + ownerId: 'worker-1', + }); + const told = pausesFollowersHearOf(session, dispatcher); + + await dispatcher.runOnce(new Date('2030-01-01T00:00:00Z')); + + if (approvedByItself) { + expect(session.respondToToolSuspension).toHaveBeenCalledWith({ + resumeData: { action: 'approved' }, + toolCallId, + requestContext: expect.any(RequestContext), + }); + expect(told).toEqual([]); + expect(dispatcher.autoApproves(toolCallId)).toBe(false); + } else { + expect(session.respondToToolSuspension).not.toHaveBeenCalled(); + expect(told).toEqual([exitTool]); + } + expect((await storage.listDeferredDecisions('org-1', PROJECT_ID))[0]?.status).toBe('succeeded'); + } + }, + ); + + it('asks a person once the phase has approved as many plans as it will, and the run plans again', async () => { + const storage = (await createFactoryStorageForTests()).workItems; + const { transitionService } = await queueBuild(storage, ['effort:low'], 'notice-plan-cap'); + const { controller, session } = createSession(undefined, { suspendsOnPlan: true, replansAfterApproval: true }); + const dispatcher = new FactoryDecisionDispatcher({ + controller: controller as never, + transitionService, + storage, + boards: autoStartingBoards(boardsWithBuilding({ exitTool: { id: 'submit_plan', autoApprove: true } })), + ownerId: 'worker-1', + }); + const told = pausesFollowersHearOf(session, dispatcher); + + await dispatcher.runOnce(new Date('2030-01-01T00:00:00Z')); + + expect(session.respondToToolSuspension).toHaveBeenCalledTimes(3); + expect(told).toEqual(['submit_plan']); + }); + + it('still asks a person about a pause that is not the exit tool of an auto-approving phase', async () => { + const storage = (await createFactoryStorageForTests()).workItems; + const { transitionService } = await queueBuild(storage, ['effort:low'], 'notice-other-tool'); + const { controller, session } = createSession(undefined, { suspendsOnTool: 'sign_off' }); + const dispatcher = new FactoryDecisionDispatcher({ + controller: controller as never, + transitionService, + storage, + boards: autoStartingBoards(boardsWithBuilding({ exitTool: { id: 'submit_plan', autoApprove: true } })), + ownerId: 'worker-1', + }); + const told = pausesFollowersHearOf(session, dispatcher); + + await dispatcher.runOnce(new Date('2030-01-01T00:00:00Z')); + + expect(session.respondToToolSuspension).not.toHaveBeenCalled(); + expect(told).toEqual(['sign_off']); + }); }); describe('review status comment lifecycle', () => { diff --git a/mastracode/factory/src/rules/dispatcher.ts b/mastracode/factory/src/rules/dispatcher.ts index 118dbc8f086..1bb47e10129 100644 --- a/mastracode/factory/src/rules/dispatcher.ts +++ b/mastracode/factory/src/rules/dispatcher.ts @@ -188,9 +188,11 @@ function reviewSeatSkill(decision: unknown): { skillName?: unknown } | undefined // Rescheduling a failure that can never succeed only delays the moment a person sees why. function isTerminalFailure(attempts: number, failureCode: FactoryDispatchFailureCode): boolean { + const failure = factoryDispatchFailureMetadata(failureCode); return ( attempts >= (failureCode === 'run_incomplete' ? 2 : MAX_ATTEMPTS) || - !factoryDispatchFailureMetadata(failureCode).canRetry + !failure.canRetry || + failure.autoRetry === false ); } @@ -221,14 +223,18 @@ function watchRun( session: Pick, { timeoutMs, - approvePlans, + autoApprovedTool, + autoApproving, requestContext, onAgentEnd, label, runStillActive, }: { timeoutMs: number; - approvePlans: boolean; + /** The tool this run answers itself when it pauses on it; any other pause waits for a person. */ + autoApprovedTool?: string; + /** Where the run says which paused calls it is about to answer. */ + autoApproving?: Set; /** The run's own request context; resuming an approved plan resolves the session's workspace with it. */ requestContext?: RequestContext; onAgentEnd?: () => Promise; @@ -242,6 +248,8 @@ function watchRun( let endReason: 'complete' | 'aborted' | 'error' | 'suspended' | undefined; let supersededAtEnd: Promise | undefined; let parked: { toolName: string; toolCallId: string } | undefined; + let approvals = 0; + const announced = new Set(); // Latest observational-memory failure seen on this run. The stream aborts the // run when observation/reflection fails, but the abort itself carries no // reason — so without this the true cause (e.g. a provider rejecting the OM @@ -278,6 +286,11 @@ function watchRun( } if (event.type === 'tool_suspended') { parked = { toolName: event.toolName, toolCallId: event.toolCallId }; + // Said before the run ends on it, so nobody is asked to answer what this run answers itself. + if (event.toolName === autoApprovedTool && approvals < MAX_PLAN_APPROVALS) { + announced.add(event.toolCallId); + autoApproving?.add(event.toolCallId); + } return; } if (event.type === 'tool_suspension_cancelled' && parked?.toolCallId === event.toolCallId) { @@ -305,19 +318,27 @@ function watchRun( endReason: () => endReason, /** The tool the run is parked on, when it ended suspended. */ parked: () => parked, - close: unsubscribe, + close: () => { + // A watch that gives up answers nothing more, so its pauses wait for a person again. + for (const toolCallId of announced) autoApproving?.delete(toolCallId); + unsubscribe(); + }, /** The run's own verdict, thrown as what the dispatcher should record. */ async settle(): Promise { let observed = await wait(); // Past the cap the plan stays parked: the person it waits for sees it in the inbox. - if (approvePlans) { - for (let approvals = 0; parked?.toolName === 'submit_plan' && approvals < MAX_PLAN_APPROVALS; approvals += 1) { - const { toolCallId } = parked; - parked = undefined; - arm(); + while (autoApprovedTool && parked?.toolName === autoApprovedTool && approvals < MAX_PLAN_APPROVALS) { + const { toolCallId } = parked; + parked = undefined; + // Counted before the resumed run can pause again, so its next pause is judged against the cap. + approvals += 1; + arm(); + try { await session.respondToToolSuspension({ resumeData: { action: 'approved' }, toolCallId, requestContext }); - observed = await wait(); + } finally { + autoApproving?.delete(toolCallId); } + observed = await wait(); } if (!observed) { // A completed decision with no observed run end is exactly the @@ -691,6 +712,7 @@ export class FactoryDecisionDispatcher { readonly #intakeRoutes?: IntakeRoutesReader; readonly #storage: WorkItemsStorage; readonly #ownerId: string; + readonly #autoApproving = new Set(); readonly #reconcileToolResults?: () => Promise; readonly #reconcileRunBinding?: FactoryDecisionDispatcherOptions['reconcileRunBinding']; readonly #prepareBinding?: (input: FactoryBindingPreparationInput) => Promise; @@ -1118,7 +1140,6 @@ export class FactoryDecisionDispatcher { if (runStillActive()) { const run = watchRun(session, { timeoutMs: this.#skillCompletionObservationTimeoutMs, - approvePlans: false, label: 'Factory skill run', runStillActive, }); @@ -1541,7 +1562,8 @@ export class FactoryDecisionDispatcher { ); const run = watchRun(session, { timeoutMs: this.#skillCompletionObservationTimeoutMs, - approvePlans: await this.#plansAreAutoApproved(record), + autoApprovedTool: await this.#autoApprovedExitTool(record), + autoApproving: this.#autoApproving, requestContext, onAgentEnd: () => this.#roleSuperseded(record, decision.role), label: 'Factory skill run', @@ -2581,10 +2603,10 @@ export class FactoryDecisionDispatcher { } /** - * Whether the run answers its plan approvals itself: the card's phase ends with an auto-approved - * `submit_plan`. Otherwise a plan waits for a person. + * The tool whose pauses the run answers itself: the exit tool of the card's phase, where the + * board approves it without a person for this card. Any other pause waits for a person. */ - async #plansAreAutoApproved({ + async #autoApprovedExitTool({ orgId, factoryProjectId, workItemId, @@ -2592,12 +2614,14 @@ export class FactoryDecisionDispatcher { orgId: string; factoryProjectId: string; workItemId: string | null; - }): Promise { + }): Promise { const item = workItemId ? await this.#storage.get({ orgId, id: workItemId }) : null; - return ( - item !== null && - autoApprovedExitTool(await this.#boards.load({ orgId, factoryProjectId }), item) === 'submit_plan' - ); + return item ? autoApprovedExitTool(await this.#boards.load({ orgId, factoryProjectId }), item) : undefined; + } + + /** Whether a run this dispatcher watches is about to approve `toolCallId` itself, so no person needs asking. */ + autoApproves(toolCallId: string): boolean { + return this.#autoApproving.has(toolCallId); } /** @@ -2628,7 +2652,6 @@ export class FactoryDecisionDispatcher { while (true) { const openRun = watchRun(session, { timeoutMs: this.#skillCompletionObservationTimeoutMs, - approvePlans: false, label, runStillActive, }); @@ -2850,7 +2873,8 @@ export class FactoryDecisionDispatcher { const since = new Date(); const run = watchRun(session, { timeoutMs: this.#skillCompletionObservationTimeoutMs, - approvePlans: await this.#plansAreAutoApproved({ ...record, workItemId: binding.workItemId }), + autoApprovedTool: await this.#autoApprovedExitTool({ ...record, workItemId: binding.workItemId }), + autoApproving: this.#autoApproving, requestContext, label: 'Factory kickoff run', runStillActive: () => diff --git a/mastracode/factory/src/rules/start-coordinator.test.ts b/mastracode/factory/src/rules/start-coordinator.test.ts index 1082f34538e..2e9b94aaeaf 100644 --- a/mastracode/factory/src/rules/start-coordinator.test.ts +++ b/mastracode/factory/src/rules/start-coordinator.test.ts @@ -7,6 +7,7 @@ import { DEFAULT_OBSERVATION_THRESHOLD, DEFAULT_REFLECTION_THRESHOLD } from '../ import { createFactoryStorageForTests } from '../storage/test-utils.js'; import { FactoryStartCoordinator } from './start-coordinator.js'; import { FactoryTransitionService } from './transition-service.js'; +import type { FactoryRuleActor } from './types.js'; const { primeTenant } = vi.hoisted(() => ({ primeTenant: vi.fn() })); vi.mock('../routes/tenant-credentials.js', async importOriginal => { @@ -485,6 +486,68 @@ describe('FactoryStartCoordinator', () => { expect((await storage.listPendingStarts('org-1', PROJECT_ID))[0]?.status).toBe('sent'); }); + describe('who a start that moves the card is recorded as', () => { + const FACTORY = `factory-project:${PROJECT_ID}`; + + async function startOnFactorySession(startedBy?: FactoryRuleActor) { + const storage = (await createFactoryStorageForTests()).workItems; + const audit = vi.fn(async (_event: { actorId: string; actorType: string }) => null); + const transitionService = new FactoryTransitionService({ + storage, + configVersion: 'rules-v1', + boards: createPolicyTestRegistry(async () => undefined), + audit: { record: audit } as never, + }); + const transition = vi.spyOn(transitionService, 'transition'); + const sourceControl = makeSourceControl(); + // The Factory owns the session the run starts in. + const session = await sourceControl.sessions.getBySessionId('session-1'); + (session as { userId: string }).userId = FACTORY; + const coordinator = new FactoryStartCoordinator( + makeController().controller as never, + storage, + transitionService, + sourceControl as never, + ); + const prepared = await coordinator.prepare({ + ...startRequest(), + userId: FACTORY, + destinationStage: 'execute', + ...(startedBy ? { startedBy } : {}), + }); + const item = await storage.get({ orgId: 'org-1', id: prepared.workItemId }); + const entered = item?.stageHistory.find(entry => entry.stage === 'execute'); + const [recorded] = audit.mock.calls.map(([event]) => ({ actorId: event.actorId, actorType: event.actorType })); + return { movedAs: transition.mock.calls[0]![0].actor, enteredBy: entered?.by, recorded }; + } + + it('names the person who started the work, not the Factory that owns the session', async () => { + await expect(startOnFactorySession({ type: 'human', id: 'user-mover' })).resolves.toEqual({ + movedAs: { type: 'human', id: 'user-mover' }, + enteredBy: 'user-mover', + recorded: { actorId: 'user-mover', actorType: 'human' }, + }); + }); + + it('names the Factory as a system, never a person, when nobody started the work', async () => { + await expect(startOnFactorySession()).resolves.toEqual({ + movedAs: { type: 'system', id: FACTORY }, + enteredBy: FACTORY, + recorded: { actorId: FACTORY, actorType: 'system' }, + }); + }); + + it('names the agent that started the work as an agent, never a person', async () => { + await expect( + startOnFactorySession({ type: 'agent', bindingId: 'binding-earlier', role: 'triage' }), + ).resolves.toEqual({ + movedAs: { type: 'agent', bindingId: 'binding-earlier', role: 'triage' }, + enteredBy: 'agent:binding-earlier', + recorded: { actorId: 'agent:binding-earlier', actorType: 'agent' }, + }); + }); + }); + it('binds the controller session to the exact Factory session thread', async () => { const storage = (await createFactoryStorageForTests()).workItems; const { controller, session } = makeController(); diff --git a/mastracode/factory/src/rules/start-coordinator.ts b/mastracode/factory/src/rules/start-coordinator.ts index 009bdd22500..d6735f85679 100644 --- a/mastracode/factory/src/rules/start-coordinator.ts +++ b/mastracode/factory/src/rules/start-coordinator.ts @@ -11,17 +11,23 @@ import { hydrateFactorySession, resolveFactorySessionModel } from '../session/fa import { resolveWorkItemRepository } from '../session/work-item-repository.js'; import type { IntakeStorage } from '../storage/domains/intake/base.js'; import type { ModelDefaultsStorage } from '../storage/domains/model-defaults/base.js'; +import { isFactoryPrincipalId } from '../storage/domains/projects/base.js'; import type { EffectiveModelScope, FactoryProjectsStorage } from '../storage/domains/projects/base.js'; import type { SourceControlSession, SourceControlStorageHandle } from '../storage/domains/source-control/base.js'; import type { CreateWorkItemInput, WorkItemsStorage } from '../storage/domains/work-items/base.js'; import type { FactoryTransitionService } from './transition-service.js'; import { externallyAuthoredWorkItem } from './types.js'; -import type { FactoryRuleStage, FactoryTransitionResult } from './types.js'; +import type { FactoryRuleActor, FactoryRuleStage, FactoryTransitionResult } from './types.js'; export interface FactoryStartRequest { orgId: string; userId: string; factoryProjectId: string; + /** + * Who started the work, where that is not the session's owner: the Factory owns the + * sessions it runs, and the move a start makes is still the mover's. + */ + startedBy?: FactoryRuleActor; sessionId: string; threadTitle: string; kickoffKey: string; @@ -365,7 +371,11 @@ export class FactoryStartCoordinator { board: boardForWorkItem(prepared.item), stage: destinationStage, expectedRevision: prepared.item.revision, - actor: { type: 'human', id: request.userId }, + actor: + request.startedBy ?? + (isFactoryPrincipalId(request.userId) + ? { type: 'system', id: request.userId } + : { type: 'human', id: request.userId }), ingress: { type: 'human', identity: `start:${request.kickoffKey}:transition` }, cause: 'run_start', }); diff --git a/mastracode/factory/src/rules/transition-service.ts b/mastracode/factory/src/rules/transition-service.ts index 52da7428073..0f261ae9227 100644 --- a/mastracode/factory/src/rules/transition-service.ts +++ b/mastracode/factory/src/rules/transition-service.ts @@ -8,6 +8,7 @@ import { boardFlow, boardForWorkItem, hasPullRequest, pullRequestCardRejection } import { boardTransitionPolicyResultSchema, immutablePolicySnapshot } from '../boards/transition-policy.js'; import type { AuditActorProfileInput, AuditActorType, AuditContext } from '../storage/domains/audit/base.js'; import type { AuditRecorder } from '../storage/domains/audit/domain.js'; +import { isFactoryPrincipalId } from '../storage/domains/projects/base.js'; import { isAgentActor } from '../storage/domains/work-items/base.js'; import type { Card, WorkItemsStorage } from '../storage/domains/work-items/base.js'; import type { @@ -171,7 +172,7 @@ export function auditActorOf(actor: FactoryRuleActor): { actorId: string; actorT case 'gitlab': return { actorId: id, actorType: 'human' }; case 'human': - return { actorId: id, actorType: isAgentActor(id) ? 'agent' : 'human' }; + return { actorId: id, actorType: isAgentActor(id) ? 'agent' : isFactoryPrincipalId(id) ? 'system' : 'human' }; default: return { actorId: id, actorType: actor.type }; } @@ -542,6 +543,8 @@ export class FactoryTransitionService { const exitTool = fromPhase?.kind === 'working' ? fromPhase.exitTool : undefined; if ( request.actor.type !== 'human' && + // A start lands the card where its run already is; it is not the agent leaving a phase. + request.cause !== 'run_start' && !request.eventRoute && exitTool && fromStage !== request.stage && diff --git a/mastracode/factory/src/session/factory-session.ts b/mastracode/factory/src/session/factory-session.ts index 59a3ea3ebbd..0984d466982 100644 --- a/mastracode/factory/src/session/factory-session.ts +++ b/mastracode/factory/src/session/factory-session.ts @@ -2,9 +2,12 @@ import type { MastraCodeState } from '@mastra/code-sdk/schema'; import type { AgentController } from '@mastra/core/agent-controller'; import { resolveTenantProviderDefaultModel } from '../routes/tenant-credentials.js'; +import { FactoryDispatchError } from '../rules/dispatch-errors.js'; +import type { ModelCredentialsStorage } from '../storage/domains/credentials/base.js'; +import type { CustomProvidersStorage } from '../storage/domains/custom-providers/base.js'; import type { ModelDefaultsStorage } from '../storage/domains/model-defaults/base.js'; -import { effectiveModelScope } from '../storage/domains/projects/base.js'; -import type { EffectiveModelScope, FactoryProjectsStorage } from '../storage/domains/projects/base.js'; +import { effectiveModelScope, factoryPrincipalId } from '../storage/domains/projects/base.js'; +import type { EffectiveModelScope, FactoryProject, FactoryProjectsStorage } from '../storage/domains/projects/base.js'; import { SourceControlConnectionNotFoundError } from '../storage/domains/source-control/base.js'; import type { SourceControlSession, @@ -268,10 +271,9 @@ export async function resolvePrimaryEnvironmentRepository(args: { * repository's pinned or default branch as the base. The sandbox itself boots * every environment repository. * - * The run is attributed to `attributeToUserId` when the caller has an - * interactive user (e.g. the approver of a proposed run), and otherwise falls - * back to whoever connected the repository (`connection.createdByUserId`), - * because a genuinely autonomous run has no interactive user of its own. + * The run is attributed to `attributeToUserId` when the caller names a person + * for it, and only otherwise falls back to whoever connected the repository + * (`connection.createdByUserId`). */ export async function ensureFactorySourceSession( args: EnsureFactorySourceSessionArgs, @@ -388,3 +390,34 @@ export async function hydrateFactorySession( // Callers pin this id to the thread, so only report a model the session actually runs on. return switched ? selectedModelId : undefined; } + +/** Where a Factory-owned run can find a model to call. */ +export interface OrganizationModelSources { + modelCredentials?: Pick; + /** OpenAI-compatible providers the organization configured, each with its own key. */ + customProviders?: Pick; + /** Providers that run on the server process's own credentials, so need no stored key. */ + deploymentModelProviders?: ReadonlySet; +} + +/** + * A run owned by the Factory reaches models through the organization alone: its stored + * keys and the providers it configured. With neither it cannot run however often it is + * retried, so say what to add instead of starting a run that dies on its first model call. + */ +export async function requireOrganizationModelKey( + sources: OrganizationModelSources | undefined, + project: Pick, +): Promise { + if (!sources?.modelCredentials || sources.deploymentModelProviders?.size) return; + const credentials = await sources.modelCredentials.listCredentials(project.orgId, factoryPrincipalId(project.id)); + if (credentials.some(credential => credential.scope === 'org')) return; + if (sources.customProviders) { + await sources.customProviders.ensureReady(); + if ((await sources.customProviders.list({ orgId: project.orgId })).length) return; + } + throw new FactoryDispatchError( + 'factory_org_key_missing', + "This Factory runs its cards on the organization's model keys, and none is set. Add an organization key or provider under Settings → Models, then retry.", + ); +} diff --git a/mastracode/factory/src/storage/domains/audit/actors.ts b/mastracode/factory/src/storage/domains/audit/actors.ts index 245509454f9..f233383480d 100644 --- a/mastracode/factory/src/storage/domains/audit/actors.ts +++ b/mastracode/factory/src/storage/domains/audit/actors.ts @@ -17,5 +17,11 @@ const AUTOMATION_ACTORS = new Set([ export function isHumanActorId(actorId: string | undefined): actorId is string { if (!actorId) return false; - return !AUTOMATION_ACTORS.has(actorId) && !actorId.startsWith('agent:') && !actorId.startsWith('github:'); + return ( + !AUTOMATION_ACTORS.has(actorId) && + !actorId.startsWith('agent:') && + !actorId.startsWith('github:') && + // A Factory running its own automatic work (`factoryPrincipalId`). + !actorId.startsWith('factory-project:') + ); } diff --git a/mastracode/factory/src/storage/domains/projects/base.ts b/mastracode/factory/src/storage/domains/projects/base.ts index 71bc648a949..94824be8763 100644 --- a/mastracode/factory/src/storage/domains/projects/base.ts +++ b/mastracode/factory/src/storage/domains/projects/base.ts @@ -29,6 +29,18 @@ export function factoryProjectSettingsUserId(factoryProjectId: string): string { return `factory-project:${factoryProjectId}`; } +/** + * The Factory as the owner of work nobody started: the `user_id` of a phase session a + * webhook, an automatic phase or a rule opened, and the user its runs authenticate as. + * It is the settings sentinel, so such a run reads the Factory's own settings rows and, + * having no personal rows, only ever resolves the organization's model keys. + */ +export const factoryPrincipalId = factoryProjectSettingsUserId; + +export function isFactoryPrincipalId(userId: string | null | undefined): boolean { + return userId?.startsWith('factory-project:') === true; +} + export interface FactoryProject { id: string; orgId: string; diff --git a/mastracode/factory/src/storage/domains/work-items/base.ts b/mastracode/factory/src/storage/domains/work-items/base.ts index 39da0defdd2..80082bbc2f5 100644 --- a/mastracode/factory/src/storage/domains/work-items/base.ts +++ b/mastracode/factory/src/storage/domains/work-items/base.ts @@ -243,6 +243,7 @@ const FACTORY_DISPATCH_FAILURE_CODES = [ 'run_configuration_invalid', 'run_credentials_unavailable', 'run_user_unauthenticated', + 'factory_org_key_missing', 'run_failed', 'unknown', ] as const; @@ -628,8 +629,8 @@ export const FACTORY_WORK_ITEM_SUBSCRIPTIONS_SCHEMA: CollectionSchema = { ], }; -/** Why a session follows a work item: it filed it, started a role on it, or asked to. */ -export type WorkItemSubscriptionReason = 'created' | 'started' | 'subscribed'; +/** Why a session follows a work item: it filed it, moved it, started a role on it, or asked to. */ +export type WorkItemSubscriptionReason = 'created' | 'moved' | 'started' | 'subscribed'; /** A session following a work item, so it hears what happens to it. */ export interface WorkItemSubscription { @@ -3393,6 +3394,22 @@ export class WorkItemsStorage extends FactoryStorageDomain { }); } + /** The binding an `agent:` actor names, active or revoked. Identifies; never authorizes. */ + async findRunBindingById(input: { + orgId: string; + factoryProjectId: string; + id: string; + }): Promise { + // Actor ids are free text and the id column is a uuid on Postgres. + if (!/^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(input.id)) return null; + const row = await this.#db.findOne('factory_run_bindings', { + id: input.id, + org_id: input.orgId, + factory_project_id: input.factoryProjectId, + }); + return row ? toBinding(row) : null; + } + /** Resolve exact active agent authority; partial session matches never authorize. */ async findActiveRunBinding(address: FactoryRunBindingAddress): Promise { const row = await this.#db.findOne('factory_run_bindings', { @@ -4171,6 +4188,27 @@ export class WorkItemsStorage extends FactoryStorageDomain { return rows.map(toWorkItemSubscription); } + /** Every follow link in a Factory, earliest first: which session follows which work item. */ + async listProjectSubscriptions({ + orgId, + factoryProjectId, + }: { + orgId: string; + factoryProjectId: string; + }): Promise { + const rows = await super.ops.findMany( + FACTORY_WORK_ITEM_SUBSCRIPTIONS_SCHEMA.name, + { org_id: orgId, factory_project_id: factoryProjectId }, + { + orderBy: [ + ['created_at', 'asc'], + ['id', 'asc'], + ], + }, + ); + return rows.map(toWorkItemSubscription); + } + /** The work items one session follows in a Factory, earliest first. */ async listSessionSubscriptions({ orgId, diff --git a/mastracode/factory/src/tools/approval-answer-resume.test.ts b/mastracode/factory/src/tools/approval-answer-resume.test.ts new file mode 100644 index 00000000000..45e05329725 --- /dev/null +++ b/mastracode/factory/src/tools/approval-answer-resume.test.ts @@ -0,0 +1,652 @@ +import { randomUUID } from 'node:crypto'; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; + +import { LLMock } from '@copilotkit/aimock'; +import { createMastraCode } from '@mastra/code-sdk'; +import { + resolveAuthenticatedCredentialTenant, + setCredentialStoreProvider, +} from '@mastra/code-sdk/agents/credential-resolver'; +import type { CredentialTenant } from '@mastra/code-sdk/agents/credential-resolver'; +import { EventEmitterPubSub } from '@mastra/core/events'; +import { RequestContext } from '@mastra/core/request-context'; +import { createTool } from '@mastra/core/tools'; +import { LibSQLStore } from '@mastra/libsql'; +import { PostgresStore } from '@mastra/pg'; +import { Hono } from 'hono'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { z } from 'zod'; + +import { createBoardRegistry } from '../boards/index.js'; +import { buildSourceControlSessionRoutes } from '../routes/source-control-sessions.js'; +import { + registerTenantCredentialResolver, + resetTenantCredentialResolverForTests, +} from '../routes/tenant-credentials.js'; +import { fakeRouteAuth, mountApiRoutes } from '../routes/test-utils.js'; +import { resolveFactoryCredentialTenant } from '../session/credential-policy.js'; +import { factoryPrincipalId } from '../storage/domains/projects/base.js'; +import { createFactoryStorageForTests } from '../storage/test-utils.js'; +import { createFactoryApprovalTools } from './approval-tools.js'; +import { createSessionApprovalNotifier, createSessionRunEndReporter } from './reports.js'; +import { observeSessionRunReports } from './run-watch.js'; +import type { FactoryToolScope } from './scope.js'; +import { createFactoryWorkItemTools } from './work-item-tools.js'; + +vi.setConfig({ testTimeout: 60_000 }); + +const ORG = 'org-1'; +const OWNER = 'user-owner'; +const REQUESTER = 'user-requester'; +const STRANGER = 'user-stranger'; +const MODEL = 'gpt-5.4-mini'; +const postgresUrl = process.env.FACTORY_TEST_POSTGRES_URL; + +let directory: string; +let mock: LLMock; +let resolved: Array; +let stops: Array<() => Promise | void>; + +beforeEach(async () => { + directory = mkdtempSync(path.join(tmpdir(), 'factory-approval-answer-')); + mock = new LLMock({ port: 0 }); + await mock.start(); + vi.stubEnv('OPENAI_BASE_URL', `${mock.url.replace(/\/+$/, '')}/v1`); + vi.stubEnv('OPENAI_API_KEY', 'process-env-key-must-not-be-used'); + vi.stubEnv('MASTRA_APP_DATA_DIR', path.join(directory, 'app-data')); + vi.stubEnv('MASTRACODE_DISABLE_UNIX_SOCKET_PUBSUB', '1'); + vi.stubEnv('MASTRACODE_DISABLE_OBSERVATIONAL_MEMORY', '1'); + resolved = []; + stops = []; + // Every model call resolves its credentials through here, as a Factory server's do. + setCredentialStoreProvider( + tenant => { + const key = `key-for-${tenant.userId}`; + return { + allowEnvironmentFallback: false, + reload: () => {}, + get: () => ({ type: 'api_key', key }), + getStoredApiKey: () => key, + getApiKey: async () => key, + }; + }, + async requestContext => { + const tenant = resolveAuthenticatedCredentialTenant(requestContext); + resolved.push(tenant); + return tenant; + }, + ); +}); + +afterEach(async () => { + resetTenantCredentialResolverForTests(); + for (const stop of stops.splice(0).reverse()) await stop(); + await mock.stop(); + vi.unstubAllEnvs(); + rmSync(directory, { recursive: true, force: true }); +}); + +async function sessionStorage(backend: string) { + if (backend === 'libsql') { + return new LibSQLStore({ id: 'approval-answer', url: `file:${path.join(directory, 'mastra.db')}` }); + } + const schemaName = `approval_answer_${randomUUID().replaceAll('-', '')}`; + const storage = new PostgresStore({ id: 'approval-answer', connectionString: postgresUrl!, schemaName }); + stops.push(async () => { + // The resumed run can still be saving its last messages; Postgres aborts one side, so ask again. + await vi.waitFor(() => storage.pool.query(`DROP SCHEMA IF EXISTS "${schemaName}" CASCADE`), { timeout: 10_000 }); + await storage.close(); + }); + return storage; +} + +/** What the phase session's run stops on, and the tool call that holds it. */ +const PARKED = { + /** The plan tool pauses itself and resumes on the answer. */ + plan: { toolCallId: 'call_plan', toolName: 'submit_plan' }, + /** A board's own tool that may not run until a person agrees. */ + release: { toolCallId: 'call_release', toolName: 'ship_release' }, + /** A question to the person: an answer, not a yes or no. */ + question: { toolCallId: 'call_question', toolName: 'ask_user' }, +} as const; + +/** + * A card's phase session, owned by one person, stops on a tool call that waits for approval. + * The person who asked for the work follows the card from their own session and answers there. + */ +describe.each(['libsql', ...(postgresUrl ? ['postgres'] : [])])( + 'a tool call waiting for approval, answered from a session following the card (%s)', + backend => { + async function parkedPhaseSession(options?: { + ownedByFactory?: boolean; + parkedOn?: keyof typeof PARKED; + /** The person moved the card from their own session, rather than filing it. */ + movedFromOwnSession?: boolean; + }) { + const parkedOn = options?.parkedOn ?? 'plan'; + const parked = PARKED[parkedOn]; + const settingsPath = path.join(directory, 'settings.json'); + writeFileSync( + settingsPath, + JSON.stringify({ + onboarding: { skippedAt: '2026-01-01T00:00:00.000Z', version: 1 }, + models: { activeModelPackId: null, modeDefaults: { build: `openai/${MODEL}`, plan: `openai/${MODEL}` } }, + }), + ); + const plansDir = path.join(directory, 'plans'); + mkdirSync(plansDir, { recursive: true }); + const planPath = path.join(plansDir, 'fix.md'); + writeFileSync(planPath, '# Fix\n\n1. Do it.\n'); + const toolArguments = { + plan: { path: planPath }, + release: { version: '1.2.0' }, + question: { question: 'Which branch should this target?' }, + }[parkedOn]; + mock.on( + { sequenceIndex: 0 }, + { toolCalls: [{ id: parked.toolCallId, name: parked.toolName, arguments: JSON.stringify(toolArguments) }] }, + ); + mock.onMessage(/.*/, { content: 'Carrying on.' }); + const shipped: string[] = []; + + const code = await createMastraCode({ + cwd: directory, + homeDir: directory, + configDir: '.mastracode-test', + settingsPath, + storage: await sessionStorage(backend), + storageBackend: backend === 'libsql' ? 'libsql' : 'pg', + pubsub: new EventEmitterPubSub(), + disableMcp: true, + disableHooks: true, + disableEnvFile: true, + disablePlugins: true, + disableGithubSignals: true, + createInitialThread: false, + plansDir, + // Tools run unasked by default; this session asks a person first, as a gated Factory tool does. + ...(parkedOn === 'release' ? { initialState: { yolo: false } } : {}), + extraTools: { + ship_release: createTool({ + id: 'ship_release', + description: 'Ship a release. A person approves each one.', + inputSchema: z.object({ version: z.string() }), + requireApproval: true, + execute: async ({ version }) => { + shipped.push(version); + return { shipped: version }; + }, + }), + }, + }); + stops.push(() => code.controller.shutdown?.()); + + const seeded = await createFactoryStorageForTests(); + const sourceControl = seeded.sourceControl.forIntegration('github'); + const project = await seeded.projects.create({ orgId: ORG, userId: OWNER, input: { name: 'Mastra' } }); + const installation = await sourceControl.installations.upsert({ + orgId: ORG, + connectedByUserId: OWNER, + externalId: '123', + }); + const repository = await sourceControl.repositories.upsert({ + orgId: ORG, + input: { installationId: installation.id, externalId: '456', slug: 'mastra-ai/mastra', defaultBranch: 'main' }, + }); + const connection = await sourceControl.connections.create({ + orgId: ORG, + factoryProjectId: project.id, + installationId: installation.id, + createdByUserId: OWNER, + }); + const link = await sourceControl.projectRepositories.link({ + orgId: ORG, + connectionId: connection.id, + repositoryId: repository.id, + createdByUserId: OWNER, + sandboxProvider: 'local', + sandboxWorkdir: '/sandbox/mastra', + }); + // A phase nobody started is the Factory's own; one a person started is theirs. + const owner = options?.ownedByFactory ? factoryPrincipalId(project.id) : OWNER; + if (options?.ownedByFactory) { + // The Factory server's own wiring: who pays is read from the session row, and keys from storage. + await seeded.credentials.setCredential({ orgId: ORG }, 'openai', { type: 'api_key', key: 'sk-organization' }); + registerTenantCredentialResolver(seeded.credentials, new Set(), async requestContext => { + const tenant = await resolveFactoryCredentialTenant(requestContext, { + projects: seeded.projects, + sourceControl: { getBySessionId: sessionId => sourceControl.sessions.getBySessionId(sessionId) }, + workItems: seeded.workItems, + }); + resolved.push(tenant); + return tenant; + }); + } + const phase = await sourceControl.sessions.create({ + sessionId: randomUUID(), + projectRepositoryId: link.id, + factoryProjectId: project.id, + orgId: ORG, + userId: owner, + branch: 'factory/issue-49', + baseBranch: 'main', + visibility: 'org', + }); + const { item } = await seeded.workItems.prepareRunStart({ + orgId: ORG, + userId: owner, + factoryProjectId: project.id, + workItem: { + input: { + board: 'work', + externalSource: { integrationId: 'github', type: 'issue', externalId: '49' }, + title: 'Broken login', + stages: ['plan'], + sessions: {}, + metadata: {}, + }, + }, + role: 'plan', + session: { sessionId: phase.sessionId, branch: phase.branch, threadId: phase.sessionId }, + resourceId: phase.sessionId, + kickoffKey: 'kickoff-1', + kickoffMessage: null, + }); + const requesterSessionId = randomUUID(); + await sourceControl.sessions.create({ + sessionId: requesterSessionId, + projectRepositoryId: link.id, + factoryProjectId: project.id, + orgId: ORG, + userId: REQUESTER, + branch: `user/session-${requesterSessionId}`, + baseBranch: 'main', + visibility: 'org', + }); + const scope: FactoryToolScope = { + orgId: ORG, + factoryProjectId: project.id, + userId: REQUESTER, + sessionId: requesterSessionId, + resourceId: requesterSessionId, + threadId: requesterSessionId, + kind: 'user', + interactive: true, + }; + if (options?.movedFromOwnSession) { + // The person's session moves the card with the tool its agent has. The board's rules are + // not under test here, so the move is accepted as asked. + const workItemTools = createFactoryWorkItemTools(scope, { + workItems: seeded.workItems, + boards: createBoardRegistry(), + transitionService: { + transition: async request => ({ + status: 'accepted', + transitionId: randomUUID(), + itemId: request.workItemId, + revision: request.expectedRevision + 1, + stage: request.stage, + decisions: [], + }), + }, + auditRecorder: { record: async () => null }, + sessions: { getSourceControlBySessionId: async () => sourceControl }, + } as never) as unknown as Record Promise }>; + await workItemTools.factory_transition_work_item!.execute({ workItem: item.id, stage: 'plan' }, {}); + } else { + await seeded.workItems.subscribeToWorkItem({ + orgId: ORG, + factoryProjectId: project.id, + workItemId: item.id, + sessionId: requesterSessionId, + threadId: requesterSessionId, + resourceId: requesterSessionId, + userId: REQUESTER, + reason: 'created', + }); + } + + const ownerContext = () => new RequestContext([['user', { workosId: owner, organizationId: ORG }]]); + const session = await code.controller.createSession({ + id: phase.sessionId, + resourceId: phase.sessionId, + threadId: phase.sessionId, + ownerId: owner, + requestContext: ownerContext(), + }); + const errors: string[] = []; + session.subscribe(event => { + if (event.type === 'error') errors.push(event.error.message); + }); + // What the Factory server tells the sessions following the card about this session's runs. + const signals: Array<{ sessionId: string; kind: string; priority?: string; summary: string }> = []; + const reports = { + sessions: { getBySessionId: (sessionId: string) => sourceControl.sessions.getBySessionId(sessionId) }, + workItems: seeded.workItems, + reporting: async () => ({ + notifications: { listNotifications: async () => [] }, + deliver: async ( + target: { sessionId: string }, + notification: { kind: string; priority?: string; summary: string }, + ) => { + signals.push({ + sessionId: target.sessionId, + kind: notification.kind, + priority: notification.priority, + summary: notification.summary, + }); + return { status: 'delivered' }; + }, + }), + } as never; + const reportRunEnd = createSessionRunEndReporter(reports); + const notifyApproval = createSessionApprovalNotifier(reports); + stops.push( + observeSessionRunReports( + session, + (outcome, since) => reportRunEnd({ sessionId: phase.sessionId, threadId: phase.sessionId, outcome, since }), + { + onApprovalRequested: request => + notifyApproval({ sessionId: phase.sessionId, threadId: phase.sessionId, ...request }), + }, + ), + ); + if (parkedOn === 'plan') await session.mode.switch({ modeId: 'plan' }); + void session.sendMessage({ content: 'Plan the fix.', requestContext: ownerContext() }).catch(() => {}); + /** The tool the run is stopped on, however it stopped. */ + const waitingOn = () => + session.suspensions.resolve({ toolCallId: parked.toolCallId })?.toolName ?? + session.approval.list().find(gate => gate.toolCallId === parked.toolCallId)?.toolName; + await vi.waitFor(() => expect(waitingOn()).toBe(parked.toolName), { timeout: 30_000 }); + expect(errors).toEqual([]); + + const audit: Array<{ actorId: string }> = []; + const profileLookups: string[] = []; + const tools = createFactoryApprovalTools(scope, { + sessions: sourceControl.sessions, + workItems: seeded.workItems, + auditRecorder: { record: (event: { actorId: string }) => audit.push(event) } as never, + messaging: async () => ({ controller: code.controller }) as never, + }); + const answer = (decision: 'approve' | 'decline') => + ( + tools.factory_answer_approval as unknown as { + execute: (input: unknown, context: unknown) => Promise; + } + ).execute({ sessionId: phase.sessionId, toolCallId: parked.toolCallId, decision }, {}); + /** The web app, signed in as `viewer`. */ + const web = (viewer: string) => { + const app = new Hono(); + app.use('*', async (context, next) => { + context.set('factoryAuthUser' as never, { workosId: viewer, organizationId: ORG } as never); + await next(); + }); + mountApiRoutes( + app as never, + buildSourceControlSessionRoutes({ + auth: fakeRouteAuth({ isOrganizationAdmin: async () => false }), + sourceControls: [sourceControl], + projects: seeded.projects, + memorySettings: seeded.memorySettings, + users: { + getUser: async (userId: string) => { + profileLookups.push(userId); + return { id: userId, name: `Person ${userId}` }; + }, + } as never, + controller: code.controller as never, + audit: { record: (event: { actorId: string }) => audit.push(event) } as never, + workItems: seeded.workItems, + }), + ); + return app; + }; + const answerOnWeb = (viewer: string, decision: 'approve' | 'decline', toolCallId?: string) => + web(viewer).request(`/web/user-sessions/${phase.sessionId}/parked-approval`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ decision, ...(toolCallId ? { toolCallId } : {}) }), + }); + return { + answer, + answerOnWeb, + web, + errors, + audit, + session, + project, + item, + requesterSessionId, + signals, + phase, + owner, + profileLookups, + waitingOn, + shipped, + sourceControl, + }; + } + + // Technical: the resumed run takes the request context the answer hands it. It must name + // the phase session's owner, so the run keeps one identity from kickoff to finish and never + // runs with no user ("the request has no authenticated user" on a Factory server). + it("carries on as the phase session's owner, and records who approved", async () => { + const { answer, errors, audit } = await parkedPhaseSession(); + const requestsBefore = mock.getRequests().length; + resolved = []; + + await answer('approve'); + + await vi.waitFor(() => expect(mock.getRequests().length).toBeGreaterThan(requestsBefore), { timeout: 30_000 }); + expect(errors).toEqual([]); + expect(resolved.length).toBeGreaterThan(0); + expect([...new Set(resolved.map(tenant => tenant?.userId))]).toEqual([OWNER]); + expect(audit.map(event => event.actorId)).toEqual([REQUESTER]); + }); + + it('lets the person who asked approve the plan on the web, and the run carries on as its owner', async () => { + const { answerOnWeb, errors, audit } = await parkedPhaseSession(); + const requestsBefore = mock.getRequests().length; + resolved = []; + + const response = await answerOnWeb(REQUESTER, 'approve'); + + expect(response.status).toBe(200); + await vi.waitFor(() => expect(mock.getRequests().length).toBeGreaterThan(requestsBefore), { timeout: 30_000 }); + expect(errors).toEqual([]); + expect([...new Set(resolved.map(tenant => tenant?.userId))]).toEqual([OWNER]); + expect(audit.map(event => event.actorId)).toEqual([REQUESTER]); + }); + + // A card a webhook filed runs as the Factory. The person following it approves the plan; the + // run must carry on as the Factory in the organization's credential scope, never as the approver. + it.each(['tool', 'web'] as const)( + "carries on as the Factory, on the organization's credentials, when a follower approves its plan (%s)", + async surface => { + const { answer, answerOnWeb, errors, audit, owner } = await parkedPhaseSession({ ownedByFactory: true }); + const requestsBefore = mock.getRequests().length; + resolved = []; + + if (surface === 'tool') await answer('approve'); + else expect((await answerOnWeb(REQUESTER, 'approve')).status).toBe(200); + + await vi.waitFor(() => expect(mock.getRequests().length).toBeGreaterThan(requestsBefore), { timeout: 30_000 }); + expect(errors).toEqual([]); + expect([...new Set(resolved.map(tenant => `${tenant?.userId} ${tenant?.credentialScope}`))]).toEqual([ + `${owner} factory`, + ]); + expect(audit.map(event => event.actorId)).toEqual([REQUESTER]); + }, + ); + + // A person moves a card from their own session. The phase that starts is the Factory's, but the + // person's session is where it reports to: it hears the plan is waiting, and answers it there. + it("tells the session that moved the card when the Factory's phase session waits on its plan, and resumes on its answer", async () => { + const { answer, errors, audit, owner, signals, phase, requesterSessionId } = await parkedPhaseSession({ + ownedByFactory: true, + movedFromOwnSession: true, + }); + + await vi.waitFor(() => + expect(signals).toEqual([ + { + sessionId: requesterSessionId, + kind: 'blocked', + priority: 'urgent', + summary: `The plan session for "Broken login" is waiting on submit_plan and needs an answer. Approve or decline it with factory_answer_approval (sessionId "${phase.sessionId}", toolCallId "call_plan").`, + }, + ]), + ); + const requestsBefore = mock.getRequests().length; + resolved = []; + + await answer('approve'); + + await vi.waitFor(() => expect(mock.getRequests().length).toBeGreaterThan(requestsBefore), { timeout: 30_000 }); + expect(errors).toEqual([]); + expect([...new Set(resolved.map(tenant => `${tenant?.userId} ${tenant?.credentialScope}`))]).toEqual([ + `${owner} factory`, + ]); + expect(audit.map(event => event.actorId)).toEqual([REQUESTER]); + }); + + it("tells a following session when a tool in the Factory's phase session waits for a person to allow it", async () => { + const { signals, phase, requesterSessionId } = await parkedPhaseSession({ + ownedByFactory: true, + movedFromOwnSession: true, + parkedOn: 'release', + }); + + await vi.waitFor(() => expect(signals).toHaveLength(1)); + expect(signals[0]).toMatchObject({ sessionId: requesterSessionId, kind: 'approval', priority: 'urgent' }); + expect(signals[0]!.summary).toContain( + `Answer it with factory_answer_approval (sessionId "${phase.sessionId}", toolCallId "call_release")`, + ); + }); + + it('names the Factory as the owner of its own session, without looking it up as a person', async () => { + const { web, project, phase, owner, profileLookups } = await parkedPhaseSession({ ownedByFactory: true }); + + const response = await web(REQUESTER).request(`/web/factory/projects/${project.id}/sessions`); + + expect(response.status).toBe(200); + const { sessions } = (await response.json()) as { + sessions: Array<{ sessionId: string; userId: string; owner?: { id: string; name: string } }>; + }; + expect(sessions.find(row => row.sessionId === phase.sessionId)).toMatchObject({ + userId: owner, + owner: { id: owner, name: 'Factory' }, + }); + expect(profileLookups).toEqual([REQUESTER]); + }); + + it('refuses a teammate who neither owns the session nor follows its card, and leaves the plan waiting', async () => { + const { answerOnWeb, waitingOn, audit } = await parkedPhaseSession(); + const requestsBefore = mock.getRequests().length; + + const response = await answerOnWeb(STRANGER, 'approve'); + + expect(response.status).toBe(403); + expect(waitingOn()).toBe('submit_plan'); + expect(mock.getRequests().length).toBe(requestsBefore); + expect(audit).toEqual([]); + }); + + // Approval belongs to the tool, not to plans: a board's own tool that waits for a person is + // answered the same way, from the same places, and the run carries on as its owner. + it.each(['tool', 'web'] as const)( + 'lets the person who asked approve a tool call that is not a plan, and the run carries on as its owner (%s)', + async surface => { + const { answer, answerOnWeb, errors, audit, shipped } = await parkedPhaseSession({ parkedOn: 'release' }); + const requestsBefore = mock.getRequests().length; + resolved = []; + + if (surface === 'tool') { + await answer('approve'); + } else { + const response = await answerOnWeb(REQUESTER, 'approve'); + expect(response.status).toBe(200); + expect(await response.json()).toMatchObject({ answered: 'approve', ...PARKED.release }); + } + + await vi.waitFor(() => expect(shipped).toEqual(['1.2.0']), { timeout: 30_000 }); + await vi.waitFor(() => expect(mock.getRequests().length).toBeGreaterThan(requestsBefore), { timeout: 30_000 }); + expect(errors).toEqual([]); + expect([...new Set(resolved.map(tenant => tenant?.userId))]).toEqual([OWNER]); + expect(audit.map(event => event.actorId)).toEqual([REQUESTER]); + }, + ); + + it('resumes a plan once when two followers answer it at the same moment, and tells the other it was answered', async () => { + const { answerOnWeb, errors, audit, waitingOn } = await parkedPhaseSession(); + + const responses = await Promise.all([answerOnWeb(REQUESTER, 'approve'), answerOnWeb(OWNER, 'approve')]); + + expect(responses.map(response => response.status).sort()).toEqual([200, 409]); + const refused = responses.find(response => response.status === 409)!; + expect(await refused.json()).toEqual({ error: 'That call was already answered: someone else got there first.' }); + expect(audit).toHaveLength(1); + expect(waitingOn()).toBeUndefined(); + expect(errors).toEqual([]); + }); + + it('declines a tool call that is not a plan from the web, so the tool never runs', async () => { + const { answerOnWeb, errors, shipped, waitingOn } = await parkedPhaseSession({ parkedOn: 'release' }); + const requestsBefore = mock.getRequests().length; + + const response = await answerOnWeb(REQUESTER, 'decline', PARKED.release.toolCallId); + + expect(response.status).toBe(200); + await vi.waitFor(() => expect(mock.getRequests().length).toBeGreaterThan(requestsBefore), { timeout: 30_000 }); + expect(waitingOn()).toBeUndefined(); + expect(shipped).toEqual([]); + expect(errors).toEqual([]); + }); + + it('leaves a question for the person to answer in the session, rather than approving it', async () => { + const { answerOnWeb, waitingOn, audit } = await parkedPhaseSession({ parkedOn: 'question' }); + const requestsBefore = mock.getRequests().length; + + const response = await answerOnWeb(REQUESTER, 'approve'); + + expect(response.status).toBe(409); + expect(await response.json()).toEqual({ + error: 'This session is not waiting on an approval. Open it to see what it needs.', + }); + expect(waitingOn()).toBe('ask_user'); + expect(mock.getRequests().length).toBe(requestsBefore); + expect(audit).toEqual([]); + }); + + // A follow belongs to the session that made it. Once that session is handed to someone else, + // the new owner is the one who asked, and the previous owner no longer answers through it. + it('follows the session to its new owner when the following session is handed over', async () => { + const { answerOnWeb, waitingOn, sourceControl, requesterSessionId } = await parkedPhaseSession(); + await sourceControl.sessions.transferOwner({ + sessionId: requesterSessionId, + expectedUserId: REQUESTER, + toUserId: STRANGER, + }); + + expect((await answerOnWeb(REQUESTER, 'approve')).status).toBe(403); + expect(waitingOn()).toBe('submit_plan'); + + expect((await answerOnWeb(STRANGER, 'approve')).status).toBe(200); + }); + + it("tells the web app which cards each session follows, so it can list a card's sessions under it", async () => { + const { web, project, item, requesterSessionId, phase } = await parkedPhaseSession(); + + const response = await web(REQUESTER).request(`/web/factory/projects/${project.id}/sessions`); + + expect(response.status).toBe(200); + const { sessions } = (await response.json()) as { + sessions: Array<{ sessionId: string; followedWorkItemIds: string[] }>; + }; + const followed = Object.fromEntries(sessions.map(row => [row.sessionId, row.followedWorkItemIds])); + expect(followed).toEqual({ [requesterSessionId]: [item.id], [phase.sessionId]: [] }); + }); + }, +); diff --git a/mastracode/factory/src/tools/approval-tools.test.ts b/mastracode/factory/src/tools/approval-tools.test.ts index d2207e697a4..d16457a8589 100644 --- a/mastracode/factory/src/tools/approval-tools.test.ts +++ b/mastracode/factory/src/tools/approval-tools.test.ts @@ -1,11 +1,32 @@ import { describe, expect, it, vi } from 'vitest'; -import { createFactoryApprovalTools } from './approval-tools.js'; +import { answerParkedCall, createFactoryApprovalTools } from './approval-tools.js'; import type { FactoryToolScope } from './scope.js'; const WORKER = '00000000-0000-4000-8000-000000000001'; const ITEM = 'item-1'; +/** How each paused tool says what it resumes on, as the session reports it. */ +const RESUME_SCHEMAS: Record = { + submit_plan: JSON.stringify({ + type: 'object', + properties: { action: { type: 'string', enum: ['approved', 'rejected'] }, feedback: { type: 'string' } }, + required: ['action'], + }), + sign_off: JSON.stringify({ + type: 'object', + properties: { action: { type: 'string', enum: ['approved', 'rejected'] } }, + required: ['action'], + }), + // Asks for a decision and a ticket number: a bare yes or no cannot finish this call. + sign_off_with_ticket: JSON.stringify({ + type: 'object', + properties: { action: { type: 'string', enum: ['approved', 'rejected'] }, ticket: { type: 'string' } }, + required: ['action', 'ticket'], + }), + ask_user: JSON.stringify({ anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] }), +}; + const scope: FactoryToolScope = { orgId: 'org-1', factoryProjectId: 'project-1', @@ -34,11 +55,40 @@ function setup({ parkedTool?: string; } = {}) { const respondToToolApproval = vi.fn((_input: unknown) => ({ accepted: true as const })); - const respondToToolSuspension = vi.fn(async (_input: unknown) => {}); + // As the live session does: a paused call is answered by whoever claims it first, and stays + // waiting when its resume fails to start. + const address = { resourceId: 'resource-1', threadId: 'thread-1', runId: 'run-1', toolCallId: 'call-1' }; + const paused = { waiting: parkedTool !== undefined, claimed: false }; + const respondToToolSuspension = vi.fn(async (_input: unknown) => { + paused.waiting = false; + }); const session = { - approval: { isArmed: vi.fn(() => armed) }, + suspensions: { has: () => paused.waiting }, + claimToolSuspension: () => { + if (!paused.waiting) return { accepted: false as const, reason: 'no_pending_suspension' }; + if (paused.claimed) return { accepted: false as const, reason: 'not_pending' }; + paused.claimed = true; + return { accepted: true as const, address, claimKey: 'claim-1' }; + }, + releaseToolResponse: () => { + paused.claimed = false; + }, + approval: { list: () => (armed ? [{ toolCallId: 'call-1', toolName: 'factory_transition_work_item' }] : []) }, respondToToolApproval, - suspensions: { resolve: vi.fn(() => (parkedTool ? { toolName: parkedTool } : undefined)) }, + displayState: { + get: () => ({ + pendingSuspensions: new Map( + parkedTool + ? [ + [ + 'run-address', + { toolCallId: 'call-1', toolName: parkedTool, resumeSchema: RESUME_SCHEMAS[parkedTool] }, + ], + ] + : [], + ), + }), + }, respondToToolSuspension, }; const record = vi.fn(); @@ -70,7 +120,7 @@ function setup({ } describe('factory_answer_approval', () => { - it('approves a plan the session is parked on with submit_plan, as the person', async () => { + it("approves a plan the session is parked on with submit_plan, resuming as the session's owner", async () => { const { answer, respondToToolApproval, respondToToolSuspension, record } = setup({ armed: false, parkedTool: 'submit_plan', @@ -80,12 +130,15 @@ describe('factory_answer_approval', () => { expect(respondToToolApproval).not.toHaveBeenCalled(); expect(respondToToolSuspension).toHaveBeenCalledWith( - expect.objectContaining({ resumeData: { action: 'approved' }, toolCallId: 'call-1' }), + expect.objectContaining({ + resumeData: { action: 'approved' }, + address: expect.objectContaining({ toolCallId: 'call-1' }), + }), ); const { requestContext } = respondToToolSuspension.mock.calls[0]![0] as { requestContext: { get(key: string): unknown }; }; - expect(requestContext.get('user')).toEqual({ workosId: 'user-1', organizationId: 'org-1' }); + expect(requestContext.get('user')).toEqual({ workosId: 'someone-else', organizationId: 'org-1' }); expect(record).toHaveBeenCalledWith(expect.objectContaining({ action: 'factory.run.approved' })); }); @@ -99,7 +152,33 @@ describe('factory_answer_approval', () => { ); }); - it('does not answer other parked tools, like ask_user', async () => { + it('approves any tool that paused itself for a yes or no, not only a plan', async () => { + const { answer, respondToToolApproval, respondToToolSuspension } = setup({ armed: false, parkedTool: 'sign_off' }); + + await expect(answer({ decision: 'approve' })).resolves.toMatchObject({ answered: 'approve' }); + + expect(respondToToolApproval).not.toHaveBeenCalled(); + expect(respondToToolSuspension).toHaveBeenCalledWith( + expect.objectContaining({ + resumeData: { action: 'approved' }, + address: expect.objectContaining({ toolCallId: 'call-1' }), + }), + ); + }); + + it('does not approve a tool that needs more than a yes or no to carry on', async () => { + const { answer, respondToToolApproval, respondToToolSuspension } = setup({ + armed: false, + parkedTool: 'sign_off_with_ticket', + }); + + await expect(answer({ decision: 'approve' })).rejects.toThrow('Nothing is waiting on that tool call'); + + expect(respondToToolApproval).not.toHaveBeenCalled(); + expect(respondToToolSuspension).not.toHaveBeenCalled(); + }); + + it('does not answer a tool waiting on a typed answer, like ask_user', async () => { const { answer, respondToToolSuspension } = setup({ armed: false, parkedTool: 'ask_user' }); await expect(answer({ decision: 'approve' })).rejects.toThrow(/Nothing is waiting/); @@ -107,7 +186,7 @@ describe('factory_answer_approval', () => { }); it('approves the call a followed work session is holding, and audits it as the person', async () => { - const { answer, session, respondToToolApproval, record } = setup(); + const { answer, respondToToolApproval, record } = setup(); await expect(answer({ decision: 'approve' })).resolves.toEqual({ answered: 'approve', @@ -115,8 +194,13 @@ describe('factory_answer_approval', () => { toolCallId: 'call-1', }); - expect(session.approval.isArmed).toHaveBeenCalledWith({ toolCallId: 'call-1' }); - expect(respondToToolApproval).toHaveBeenCalledWith({ decision: 'approve', toolCallId: 'call-1' }); + expect(respondToToolApproval).toHaveBeenCalledWith( + expect.objectContaining({ decision: 'approve', toolCallId: 'call-1' }), + ); + const { requestContext } = respondToToolApproval.mock.calls[0]![0] as { + requestContext: { get(key: string): unknown }; + }; + expect(requestContext.get('user')).toEqual({ workosId: 'someone-else', organizationId: 'org-1' }); expect(record).toHaveBeenCalledWith( expect.objectContaining({ actorId: 'user-1', @@ -136,11 +220,17 @@ describe('factory_answer_approval', () => { const { answer, respondToToolApproval, record } = setup(); await answer({ decision: 'decline', reason: 'Keep it in triage.' }); - expect(respondToToolApproval).toHaveBeenCalledWith({ - decision: 'decline', - toolCallId: 'call-1', - declineContext: { reason: 'Keep it in triage.' }, - }); + expect(respondToToolApproval).toHaveBeenCalledWith( + expect.objectContaining({ + decision: 'decline', + toolCallId: 'call-1', + declineContext: { reason: 'Keep it in triage.' }, + }), + ); + const { requestContext } = respondToToolApproval.mock.calls[0]![0] as { + requestContext: { get(key: string): unknown }; + }; + expect(requestContext.get('user')).toEqual({ workosId: 'someone-else', organizationId: 'org-1' }); expect(record).toHaveBeenCalledWith(expect.objectContaining({ action: 'factory.run.dismissed' })); }); @@ -173,6 +263,42 @@ describe('factory_answer_approval', () => { } }); + it('lets one of two answers arriving together resume the call, and tells the other it was answered', async () => { + const { answer, respondToToolSuspension, record } = setup({ armed: false, parkedTool: 'sign_off' }); + const { promise: resuming, resolve: resumed } = Promise.withResolvers(); + const consume = respondToToolSuspension.getMockImplementation()!; + respondToToolSuspension.mockImplementationOnce(async input => { + await resuming; + await consume(input); + }); + + const first = answer({ decision: 'approve' }); + const second = answer({ decision: 'decline', reason: 'Not yet.' }); + await expect(second).rejects.toThrow('That call was already answered'); + resumed(); + + await expect(first).resolves.toMatchObject({ answered: 'approve' }); + expect(respondToToolSuspension).toHaveBeenCalledTimes(1); + expect(record).toHaveBeenCalledTimes(1); + }); + + it('does not report an answer the session could not carry on from, and leaves the call open to answer', async () => { + const { answer, respondToToolSuspension, record } = setup({ armed: false, parkedTool: 'sign_off' }); + // The session reports a failed resume to its own stream and returns; the call still waits. + respondToToolSuspension.mockImplementationOnce(async () => {}); + + await expect(answer({ decision: 'approve' })).rejects.toThrow('The answer did not reach sign_off'); + expect(record).not.toHaveBeenCalled(); + + await expect(answer({ decision: 'approve' })).resolves.toMatchObject({ answered: 'approve' }); + }); + + it('tells a second answer to a held call that it was already answered', async () => { + const { answer, respondToToolApproval } = setup(); + respondToToolApproval.mockReturnValueOnce({ accepted: false, reason: 'not_pending' } as never); + await expect(answer({ decision: 'approve' })).rejects.toThrow('That call was already answered'); + }); + it('reports an answer the session refused', async () => { const { answer, respondToToolApproval, record } = setup(); respondToToolApproval.mockReturnValueOnce({ accepted: false, reason: 'aborting' } as never); @@ -180,3 +306,43 @@ describe('factory_answer_approval', () => { expect(record).not.toHaveBeenCalled(); }); }); + +describe('answering without naming the tool call', () => { + const session = { sessionId: WORKER, userId: 'someone-else', orgId: 'org-1' }; + const answerOnly = (live: unknown) => + answerParkedCall( + { messaging: async () => ({ controller: { getSession: async () => live } }) as never }, + { session, decision: 'approve', declineReason: 'No.' }, + ); + + it('answers the one call that is waiting', async () => { + const { session: live, respondToToolApproval } = setup(); + + await expect(answerOnly(live)).resolves.toEqual({ + toolCallId: 'call-1', + toolName: 'factory_transition_work_item', + }); + expect(respondToToolApproval).toHaveBeenCalledOnce(); + }); + + it('asks which call to answer when several are waiting, answering none', async () => { + const { session: live, respondToToolApproval, respondToToolSuspension } = setup({ parkedTool: 'sign_off' }); + live.displayState.get = () => ({ + pendingSuspensions: new Map([ + ['run-address', { toolCallId: 'call-2', toolName: 'sign_off', resumeSchema: RESUME_SCHEMAS.sign_off }], + ]), + }); + + await expect(answerOnly(live)).rejects.toThrow( + 'This session waits on 2 approvals (factory_transition_work_item: call-1, sign_off: call-2). Name the toolCallId to answer.', + ); + expect(respondToToolApproval).not.toHaveBeenCalled(); + expect(respondToToolSuspension).not.toHaveBeenCalled(); + }); + + it('says to open the session when it waits on no approval', async () => { + const { session: live } = setup({ armed: false, parkedTool: 'ask_user' }); + + await expect(answerOnly(live)).rejects.toThrow('This session is not waiting on an approval. Open it'); + }); +}); diff --git a/mastracode/factory/src/tools/approval-tools.ts b/mastracode/factory/src/tools/approval-tools.ts index d4091ad0682..ef778d91be3 100644 --- a/mastracode/factory/src/tools/approval-tools.ts +++ b/mastracode/factory/src/tools/approval-tools.ts @@ -1,3 +1,4 @@ +import type { SuspensionAddress } from '@mastra/core/agent-controller'; import { RequestContext } from '@mastra/core/request-context'; import { createTool } from '@mastra/core/tools'; import { z } from 'zod'; @@ -7,6 +8,7 @@ import type { SourceControlSessionLookup } from '../session/factory-session.js'; import type { AuditRecorder } from '../storage/domains/audit/domain.js'; import type { WorkItemsStorage } from '../storage/domains/work-items/base.js'; import type { FactoryMessaging } from './messaging-tools.js'; +import { resumesOnDecision } from './run-watch.js'; import { requirePerson } from './scope.js'; import type { FactoryToolScope } from './scope.js'; @@ -17,22 +19,125 @@ export interface FactoryApprovalToolDependencies { messaging: () => Promise; } -/** The parts of a live session an answer needs: its open approval gates. */ +/** The parts of a live session an answer needs: the calls it waits on, and how each is answered. */ interface ApprovalGateSession { - approval: { isArmed(filter: { toolCallId: string }): boolean }; + approval: { list(): Array<{ toolCallId: string; toolName: string }> }; + displayState: { + get(): { pendingSuspensions: Map }; + }; respondToToolApproval(input: { decision: 'approve' | 'decline'; toolCallId: string; + requestContext?: RequestContext; declineContext?: { reason?: string }; }): { accepted: true } | { accepted: false; reason: string }; - suspensions: { resolve(filter: { toolCallId: string }): { toolName: string } | undefined }; + suspensions: { has(address: SuspensionAddress): boolean }; + /** Takes the right to answer a paused call, so two answers cannot both resume it. */ + claimToolSuspension( + toolCallId: string, + ): { accepted: true; address: SuspensionAddress; claimKey: string } | { accepted: false; reason: string }; + releaseToolResponse(claimKey: string): void; respondToToolSuspension(input: { resumeData: { action: 'approved' | 'rejected'; feedback?: string }; - toolCallId: string; + address: SuspensionAddress; requestContext?: RequestContext; }): Promise; } +const ALREADY_ANSWERED = 'That call was already answered: someone else got there first.'; + +/** A tool call waiting for a yes or no, and which of the session's two channels answers it. */ +interface WaitingApproval { + toolCallId: string; + toolName: string; + /** `gate`: the call has not run yet. `resume`: the tool paused itself to ask. */ + channel: 'gate' | 'resume'; +} + +function waitingApprovals(live: ApprovalGateSession): WaitingApproval[] { + return [ + ...live.approval.list().map(({ toolCallId, toolName }) => ({ toolCallId, toolName, channel: 'gate' as const })), + // Keyed by run address, not tool call id: read the id off each entry. + ...[...live.displayState.get().pendingSuspensions.values()] + .filter(suspension => resumesOnDecision(suspension.resumeSchema)) + .map(({ toolCallId, toolName }) => ({ toolCallId, toolName, channel: 'resume' as const })), + ]; +} + +/** + * Approve or decline a tool call a live session waits on, for a caller already allowed + * to. Any tool can wait this way; with no `toolCallId` the session's only waiting call + * is answered. The answered run carries on as the session's owner whoever answers: a + * phase session keeps one identity from kickoff to finish, and a resume never runs with + * no user. + */ +export async function answerParkedCall( + deps: Pick, + input: { + session: { sessionId: string; userId: string; orgId: string }; + toolCallId?: string; + decision: 'approve' | 'decline'; + declineReason: string; + }, +): Promise<{ toolCallId: string; toolName: string }> { + const { session, decision, declineReason } = input; + const messaging = await deps.messaging(); + if (!messaging) throw new Error('Answering approvals is not available on this server.'); + const live = (await messaging.controller.getSession(session.sessionId)) as ApprovalGateSession | null; + const waiting = live ? waitingApprovals(live) : []; + const matches = input.toolCallId ? waiting.filter(call => call.toolCallId === input.toolCallId) : waiting; + const [call] = matches; + if (!live || !call) { + throw new Error( + input.toolCallId + ? 'Nothing is waiting on that tool call any more: the run that asked has ended or it was already answered. ' + + 'Message the session with factory_signal_session if it should try again.' + : 'This session is not waiting on an approval. Open it to see what it needs.', + ); + } + if (matches.length > 1) { + throw new Error( + `This session waits on ${matches.length} approvals (${matches.map(match => `${match.toolName}: ${match.toolCallId}`).join(', ')}). Name the toolCallId to answer.`, + ); + } + const { toolCallId, toolName } = call; + const requestContext = new RequestContext(); + requestContext.set('user', { workosId: session.userId, organizationId: session.orgId }); + if (call.channel === 'resume') { + // Claimed before anything is awaited: of two answers arriving together, one resumes the call. + const claim = live.claimToolSuspension(toolCallId); + if (!claim.accepted) throw new Error(ALREADY_ANSWERED); + try { + await live.respondToToolSuspension({ + resumeData: decision === 'approve' ? { action: 'approved' } : { action: 'rejected', feedback: declineReason }, + address: claim.address, + requestContext, + }); + } finally { + live.releaseToolResponse(claim.claimKey); + } + // A resume that fails to start reports its error to the session and leaves the call waiting. + if (live.suspensions.has(claim.address)) { + throw new Error( + `The answer did not reach ${toolName}: the session could not carry on and still waits on it. Open the session to see why.`, + ); + } + return { toolCallId, toolName }; + } + const result = live.respondToToolApproval({ + decision, + toolCallId, + requestContext, + ...(decision === 'decline' ? { declineContext: { reason: declineReason } } : {}), + }); + if (!result.accepted) { + throw new Error( + result.reason === 'not_pending' ? ALREADY_ANSWERED : `The answer was not accepted (${result.reason}).`, + ); + } + return { toolCallId, toolName }; +} + /** Answers a tool call another session holds for approval. Only a signed-in person's turn may answer. */ export function createFactoryApprovalTools( scope: FactoryToolScope, @@ -41,9 +146,10 @@ export function createFactoryApprovalTools( const answer = createTool({ id: 'factory_answer_approval', description: [ - 'Approve or decline a tool call a session you follow is waiting on, as you.', + 'Approve or decline a tool call a session you follow is waiting on.', + 'The decision is recorded as yours; the run carries on as the owner of the session that asked.', 'A `factory-session` notification of kind `approval` names the session, tool, arguments and toolCallId;', - 'a `blocked` notice for a session parked on submit_plan names the toolCallId of the plan to approve or decline.', + 'a `blocked` notice for a session parked on a tool that waits for approval names the toolCallId to approve or decline.', 'Answer only what the person in this conversation agreed to; decline with a reason the session will see.', ].join(' '), inputSchema: z @@ -86,38 +192,12 @@ export function createFactoryApprovalTools( ); } - const messaging = await deps.messaging(); - if (!messaging) throw new Error('Answering approvals is not available on this server.'); - const live = (await messaging.controller.getSession(sessionId)) as ApprovalGateSession | null; - const parkedPlan = live?.suspensions.resolve({ toolCallId })?.toolName === 'submit_plan'; - if (!live || (!parkedPlan && !live.approval.isArmed({ toolCallId }))) { - throw new Error( - 'Nothing is waiting on that tool call any more: the run that asked has ended or it was already answered. ' + - 'Message the session with factory_signal_session if it should try again.', - ); - } - if (parkedPlan) { - // The resumed run acts for the person answering, so it can resolve their model credentials. - const requestContext = new RequestContext(); - requestContext.set('user', { workosId: scope.userId, organizationId: scope.orgId }); - await live.respondToToolSuspension({ - resumeData: - decision === 'approve' - ? { action: 'approved' } - : { action: 'rejected', feedback: reason ?? 'Declined by a session following it.' }, - toolCallId, - requestContext, - }); - } else { - const result = live.respondToToolApproval({ - decision, - toolCallId, - ...(decision === 'decline' - ? { declineContext: { reason: reason ?? 'Declined by a session following it.' } } - : {}), - }); - if (!result.accepted) throw new Error(`The answer was not accepted (${result.reason}).`); - } + await answerParkedCall(deps, { + session: row, + toolCallId, + decision, + declineReason: reason ?? 'Declined by a session following it.', + }); deps.auditRecorder.record({ orgId: scope.orgId, diff --git a/mastracode/factory/src/tools/reports.test.ts b/mastracode/factory/src/tools/reports.test.ts index d7a6ba62252..8ea19d8067f 100644 --- a/mastracode/factory/src/tools/reports.test.ts +++ b/mastracode/factory/src/tools/reports.test.ts @@ -305,23 +305,46 @@ describe('sendRunEndReport', () => { expect(env.deliveries).toHaveLength(2); }); - it('names the toolCallId of a parked plan so a follower can answer it', async () => { + it('tells a follower how to approve or decline a tool that paused for a yes or no, whatever the tool', async () => { const env = reporting(); await sendRunEndReport(env.reporting, { sender: SENDER, recipients: [PARENT], since: new Date(Date.now() - 1000), - outcome: { status: 'blocked', toolName: 'submit_plan', toolCallId: 'call-9' }, + outcome: { status: 'blocked', toolName: 'sign_off', toolCallId: 'call-9', decision: true }, subject: 'The work session for #7', }); expect(env.deliveries[0]!.notification).toMatchObject({ kind: 'blocked', + priority: 'urgent', summary: - 'The work session for #7 is waiting on submit_plan and needs an answer. Answer it with factory_answer_approval (toolCallId call-9).', - attributes: { 'parked-tool': 'submit_plan', 'tool-call-id': 'call-9' }, + 'The work session for #7 is waiting on sign_off and needs an answer. Approve or decline it with factory_answer_approval (sessionId "session-w", toolCallId "call-9").', + // What the chat needs to answer it in place: the session that waits, and the call. + attributes: { + 'parked-tool': 'sign_off', + 'tool-call-id': 'call-9', + 'waiting-for': 'approval', + 'from-session': SENDER.sessionId, + 'from-thread': SENDER.threadId, + }, }); }); + it('sends a question to the session that asked it, with no approval to answer', async () => { + const env = reporting(); + await sendRunEndReport(env.reporting, { + sender: SENDER, + recipients: [PARENT], + since: new Date(Date.now() - 1000), + outcome: { status: 'blocked', toolName: 'ask_user', toolCallId: 'call-9' }, + subject: 'The work session for #7', + }); + expect(env.deliveries[0]!.notification).toMatchObject({ + summary: 'The work session for #7 is waiting on ask_user and needs an answer.', + }); + expect(env.deliveries[0]!.notification.attributes).not.toHaveProperty('waiting-for'); + }); + it('names the failure code and the parked tool', async () => { const env = reporting(); const since = new Date(Date.now() - 1000); diff --git a/mastracode/factory/src/tools/reports.ts b/mastracode/factory/src/tools/reports.ts index 55d9dcbbf79..ccbe0fa53d4 100644 --- a/mastracode/factory/src/tools/reports.ts +++ b/mastracode/factory/src/tools/reports.ts @@ -229,7 +229,15 @@ export async function workItemReportAttributes( export type FactoryRunOutcome = | { status: 'done' } | { status: 'failed'; reason: string; failureCode?: string } - | { status: 'blocked'; toolName?: string; toolCallId?: string; approval?: boolean }; + | { + status: 'blocked'; + toolName?: string; + toolCallId?: string; + /** The call waits for a person to allow it. */ + approval?: boolean; + /** The tool paused itself, and a yes or no from a follower is all it needs. */ + decision?: boolean; + }; /** `waiting`: the session is waiting for an answer, so a later run owes the final report. */ export interface FactoryRunEndResult { @@ -273,8 +281,8 @@ export async function sendRunEndReport( : outcome.approval ? `${subject} is waiting for someone to approve ${outcome.toolName ?? 'a tool call'} in that session.` : `${subject} is waiting${outcome.toolName ? ` on ${outcome.toolName}` : ''} and needs an answer.${ - outcome.toolName === 'submit_plan' && outcome.toolCallId - ? ` Answer it with factory_answer_approval (toolCallId ${outcome.toolCallId}).` + outcome.decision && outcome.toolCallId + ? ` Approve or decline it with factory_answer_approval (sessionId "${sender.sessionId}", toolCallId "${outcome.toolCallId}").` : '' }`; const notification = reportNotification({ @@ -287,7 +295,7 @@ export async function sendRunEndReport( ...(outcome.status === 'failed' && outcome.failureCode ? { 'failure-code': outcome.failureCode } : {}), ...(outcome.status === 'blocked' && outcome.toolName ? { 'parked-tool': outcome.toolName } : {}), ...(outcome.status === 'blocked' && outcome.toolCallId ? { 'tool-call-id': outcome.toolCallId } : {}), - ...(outcome.status === 'blocked' && outcome.approval ? { 'waiting-for': 'approval' } : {}), + ...(outcome.status === 'blocked' && (outcome.approval || outcome.decision) ? { 'waiting-for': 'approval' } : {}), }, }); const report = (recipient: FactoryDeliveryTarget, reportKinds: string[], agentOnly = false) => diff --git a/mastracode/factory/src/tools/run-watch.ts b/mastracode/factory/src/tools/run-watch.ts index 0a0161f4975..3d0ef4517d9 100644 --- a/mastracode/factory/src/tools/run-watch.ts +++ b/mastracode/factory/src/tools/run-watch.ts @@ -7,11 +7,37 @@ import type { FactoryRunOutcome } from './reports.js'; type RunEndReason = Extract['reason']; +/** + * Whether a bare yes or no is all a paused tool needs to carry on: its resume data is an + * object whose `action` is `approved` or `rejected`, and nothing else is required. A + * question to the person (free text, a choice, a decision plus a required detail) does + * not fit, and is answered in the session itself. + */ +export function resumesOnDecision(resumeSchema: string | undefined): boolean { + if (!resumeSchema) return false; + try { + const schema = JSON.parse(resumeSchema) as { properties?: { action?: { enum?: unknown } }; required?: unknown }; + const actions = schema.properties?.action?.enum; + const required = Array.isArray(schema.required) ? schema.required : []; + return ( + Array.isArray(actions) && + actions.includes('approved') && + actions.includes('rejected') && + required.every(field => field === 'action') + ); + } catch { + return false; + } +} + /** What a run stopped on: a tool waiting for an answer, or one waiting for approval. */ export interface ParkedTool { toolName: string; toolCallId: string; + /** The call has not run yet, and waits for a person to allow it. */ approval: boolean; + /** The tool paused itself, and a bare yes or no is all it needs to carry on. */ + decision?: boolean; } export interface RunReportSession { @@ -37,7 +63,14 @@ const ERROR_MESSAGE_LENGTH = 400; export function observeSessionRunReports( session: RunReportSession, report: SessionRunEndReport, - { onApprovalRequested }: { onApprovalRequested?: SessionApprovalReport } = {}, + { + onApprovalRequested, + answersItself, + }: { + onApprovalRequested?: SessionApprovalReport; + /** Whether the Factory answers this paused call without a person, so its run carries on and nobody needs telling. */ + answersItself?: (toolCallId: string) => boolean; + } = {}, ): () => void { let parked: ParkedTool | undefined; let lastError: string | undefined; @@ -52,6 +85,7 @@ export function observeSessionRunReports( toolName: event.toolName, toolCallId: event.toolCallId, approval: event.type === 'tool_approval_required', + ...(event.type === 'tool_suspended' && resumesOnDecision(event.resumeSchema) ? { decision: true } : {}), }; // An approval gate holds the run open, so it is announced now, not at the run's end. if (event.type === 'tool_approval_required' && onApprovalRequested) { @@ -72,6 +106,8 @@ export function observeSessionRunReports( parked = undefined; lastError = undefined; if (!outcome) return; + // Not an end: the Factory answers the call and the same run carries on in its window. + if (outcome.status === 'blocked' && outcome.toolCallId && answersItself?.(outcome.toolCallId)) return; // Move the window now, so a run that starts before this report settles is judged on its own; // reports made up to the end, including its last millisecond, belong to the run that ended. const runSince = since; @@ -114,7 +150,7 @@ export function heartbeatOpenRunUntilEnd( /** `null` for an aborted run: someone stopped or steered it, which is not an outcome. */ export function runOutcome( reason: RunEndReason, - parked: Pick | undefined, + parked: ParkedTool | undefined, errorMessage?: string, ): FactoryRunOutcome | null { switch (reason) { @@ -137,6 +173,7 @@ export function runOutcome( toolName: parked.toolName, toolCallId: parked.toolCallId, ...(parked.approval ? { approval: true } : {}), + ...(parked.decision ? { decision: true } : {}), } : {}), }; diff --git a/mastracode/factory/src/tools/session-tools.test.ts b/mastracode/factory/src/tools/session-tools.test.ts index e068a8a7518..7fc10280866 100644 --- a/mastracode/factory/src/tools/session-tools.test.ts +++ b/mastracode/factory/src/tools/session-tools.test.ts @@ -1051,12 +1051,82 @@ describe('factory_start_session in work-item mode', () => { expect(request.requestContext).toBeUndefined(); }); - it("starts a work-item role in a hybrid Factory on the Factory's scope, like the Start route", async () => { - const env = await withItem(); - await env.seed.projects.update({ orgId: 'org-1', id: env.scope.factoryProjectId, input: { modelScope: 'hybrid' } }); - await env.start({ prompt: 'Go.', workItem: env.item.id, role: 'work' }); + // The person asked for the run, but the card's session is the Factory's: it runs on the + // organization's keys, and the person follows it from the session they asked in. + it.each(['hybrid', 'factory'] as const)( + 'starts a work-item role in a %s Factory as the Factory, followed by the session that asked', + async modelScope => { + const env = await withItem(); + await env.seed.projects.update({ orgId: 'org-1', id: env.scope.factoryProjectId, input: { modelScope } }); + const factory = `factory-project:${env.scope.factoryProjectId}`; - expect(env.prepare.mock.calls[0]![0]).toMatchObject({ modelScope: 'factory' }); + const result = (await env.start({ prompt: 'Go.', workItem: env.item.id, role: 'work' })) as Started; + + expect(env.prepare.mock.calls[0]![0]).toMatchObject({ + modelScope: 'factory', + userId: factory, + startedBy: { type: 'human', id: 'user-1' }, + }); + await expect(env.sessions.getBySessionId(result.sessionId)).resolves.toMatchObject({ userId: factory }); + const session = env.created.find(entry => entry.options.id === result.sessionId)!.session; + expect(session.state.get()).toMatchObject({ factoryOwnerUserId: factory, factoryModelScope: 'factory' }); + expect(session.sendSignal.mock.calls[0]![1].requestContext.get('user')).toEqual({ + workosId: factory, + organizationId: 'org-1', + }); + const after = (await env.seed.workItems.get({ orgId: 'org-1', id: env.item.id }))!; + expect(after.sessions.work).toMatchObject({ sessionId: result.sessionId, startedBy: factory }); + expect(await env.subscriptions()).toEqual([ + expect.objectContaining({ workItemId: env.item.id, userId: 'user-1', reason: 'started' }), + ]); + }, + ); + + it('refuses to start a Factory-run role while the organization has no model key, and says what to add', async () => { + const env = await withItem('org', { tenantCredentials: true }); + await env.seed.projects.update({ orgId: 'org-1', id: env.scope.factoryProjectId, input: { modelScope: 'hybrid' } }); + // The caller's own key is not the Factory's to spend. + await env.seed.credentials.setCredential({ orgId: 'org-1', userId: 'user-1' }, 'openai', { + type: 'api_key', + key: 'sk-personal', + }); + const before = await env.sessionRows(); + + await expect(env.start({ prompt: 'Go.', workItem: env.item.id, role: 'work' })).rejects.toThrow( + 'Add an organization key or provider under Settings → Models', + ); + + expect(env.prepare).not.toHaveBeenCalled(); + expect(await env.sessionRows()).toEqual(before); + expect(await env.subscriptions()).toEqual([]); + + await env.seed.credentials.setCredential({ orgId: 'org-1' }, 'openai', { type: 'api_key', key: 'sk-org' }); + await expect(env.start({ prompt: 'Go.', workItem: env.item.id, role: 'work' })).resolves.toMatchObject({ + mode: 'work-item', + }); + }); + + it('starts a Factory-run role for an organization that runs on its own provider and stores no key', async () => { + const env = await withItem('org', { tenantCredentials: true }); + await env.seed.projects.update({ orgId: 'org-1', id: env.scope.factoryProjectId, input: { modelScope: 'hybrid' } }); + await env.seed.customProviders.upsert({ + orgId: 'org-1', + userId: 'user-1', + input: { + providerId: 'acme', + name: 'Acme', + url: 'https://llm.acme.dev/v1', + apiKey: 'sk-acme', + models: ['fast-1'], + }, + }); + + await expect(env.start({ prompt: 'Go.', workItem: env.item.id, role: 'work' })).resolves.toMatchObject({ + mode: 'work-item', + }); + expect(env.prepare).toHaveBeenCalledWith( + expect.objectContaining({ userId: `factory-project:${env.scope.factoryProjectId}` }), + ); }); it("bills the work-item session to the caller's credential tenant", async () => { diff --git a/mastracode/factory/src/tools/session-tools.ts b/mastracode/factory/src/tools/session-tools.ts index b59cbeabd22..4654c3e8087 100644 --- a/mastracode/factory/src/tools/session-tools.ts +++ b/mastracode/factory/src/tools/session-tools.ts @@ -19,6 +19,7 @@ import type { SourceControlSessionLookup } from '../session/factory-session.js'; import { ensureFactorySourceSession, hydrateFactorySession, + requireOrganizationModelKey, resolveFactorySessionModel, } from '../session/factory-session.js'; import { recordSessionRunStart } from '../session/run-audit.js'; @@ -28,7 +29,7 @@ import type { ModelCredentialsStorage } from '../storage/domains/credentials/bas import type { CustomProvidersStorage } from '../storage/domains/custom-providers/base.js'; import type { IntakeStorage } from '../storage/domains/intake/base.js'; import type { ModelDefaultsStorage } from '../storage/domains/model-defaults/base.js'; -import { effectiveModelScope } from '../storage/domains/projects/base.js'; +import { effectiveModelScope, factoryPrincipalId } from '../storage/domains/projects/base.js'; import type { FactoryProjectsStorage } from '../storage/domains/projects/base.js'; import type { SourceControlStorageHandle } from '../storage/domains/source-control/base.js'; import type { Card, WorkItemsStorage } from '../storage/domains/work-items/base.js'; @@ -407,6 +408,19 @@ export function createFactorySessionTools( if (!project) throw new Error('This Factory no longer exists.'); // A work-item start is a run, so a hybrid Factory uses the Factory's scope (as the Start route does). const modelScope = effectiveModelScope(project.modelScope, 'run'); + // On the Factory's credentials the card's session is the Factory's own, as when the board starts it; + // the person asking stays the one who started it, and follows it from this session. + const ownerUserId = modelScope === 'factory' ? factoryPrincipalId(project.id) : scope.userId; + if (modelScope === 'factory') { + await requireOrganizationModelKey( + { + modelCredentials: deps.sessionModel.tenantCatalog?.credentials, + customProviders: deps.sessionModel.tenantCatalog?.customProviders, + deploymentModelProviders: deps.sessionModel.tenantCatalog?.deploymentProviders, + }, + project, + ); + } const projectRepositoryId = await resolveRepository(sourceControl, item); const sessionId = globalThis.crypto.randomUUID(); @@ -417,7 +431,7 @@ export function createFactorySessionTools( sessionId, branch: `${USER_SESSION_BRANCH_PREFIX}${sessionId}`, projectRepositoryId, - attributeToUserId: scope.userId, + attributeToUserId: ownerUserId, // A run works a shared card, so the org can open it and answer its approvals even when the session that // started it is private. visibility: 'org', @@ -443,7 +457,8 @@ export function createFactorySessionTools( try { prepared = await coordinator.prepare({ orgId: scope.orgId, - userId: scope.userId, + userId: ownerUserId, + startedBy: { type: 'human', id: scope.userId }, factoryProjectId: scope.factoryProjectId, sessionId: ensured.sessionId, threadTitle: title ?? `${label} ${role}`, @@ -497,7 +512,7 @@ export function createFactorySessionTools( // The run's end reaches this item's followers through the session's listener. const heartbeat = heartbeatOpenRunUntilEnd(session, kickoffId); const kickoffContext = new RequestContext(); - kickoffContext.set('user', { workosId: scope.userId, organizationId: scope.orgId }); + kickoffContext.set('user', { workosId: ownerUserId, organizationId: scope.orgId }); try { await session.sendSignal( { id: kickoffId, type: 'user', tagName: 'user', contents: prompt }, diff --git a/mastracode/factory/src/tools/work-item-tools.test.ts b/mastracode/factory/src/tools/work-item-tools.test.ts index 5ac981c76b9..f91bcc8ef31 100644 --- a/mastracode/factory/src/tools/work-item-tools.test.ts +++ b/mastracode/factory/src/tools/work-item-tools.test.ts @@ -441,6 +441,59 @@ describe('factory_transition_work_item', () => { ); }); + // The move can start a phase session the Factory owns; following is how this session hears it wait. + it('follows the card it moved, so the session hears from the run the move starts', async () => { + const { run, fileItem, workItems } = await setup(); + const { item } = await fileItem('project-1', 'Move me'); + + await run('factory_transition_work_item', { workItem: item.id, stage: 'triage' }); + + expect(await workItems.listWorkItemSubscribers({ orgId: 'org-1', workItemId: item.id })).toEqual([ + expect.objectContaining({ sessionId: 'session-1', userId: 'user-1', reason: 'moved' }), + ]); + }); + + it('still reports the move when following the card fails, so the agent does not move it twice', async () => { + const { run, fileItem, workItems } = await setup(); + const { item } = await fileItem('project-1', 'Move me'); + vi.spyOn(workItems, 'subscribeToWorkItem').mockRejectedValue(new Error('storage is away')); + + await expect(run('factory_transition_work_item', { workItem: item.id, stage: 'triage' })).resolves.toEqual({ + workItemId: item.id, + stage: 'triage', + revision: item.revision + 1, + warnings: ['This session does not follow it yet: storage is away'], + }); + }); + + it('keeps "created" when a session moves a card it filed', async () => { + const { run, workItems } = await setup(); + const created = await run<{ id: string }>('factory_create_work_item', { title: 'Mine', description: 'b' }); + + await run('factory_transition_work_item', { workItem: created.id, stage: 'triage' }); + + expect(await workItems.listWorkItemSubscribers({ orgId: 'org-1', workItemId: created.id })).toEqual([ + expect.objectContaining({ sessionId: 'session-1', reason: 'created' }), + ]); + }); + + it('does not follow a card whose move the board refused', async () => { + const { run, fileItem, workItems } = await setup({ + transition: async request => ({ + status: 'rejected', + transitionId: 't', + itemId: request.workItemId, + code: 'stale', + reason: 'The item changed.', + }), + }); + const { item } = await fileItem('project-1', 'Stale'); + + await expect(run('factory_transition_work_item', { workItem: item.id, stage: 'triage' })).rejects.toThrow(); + + expect(await workItems.listWorkItemSubscribers({ orgId: 'org-1', workItemId: item.id })).toEqual([]); + }); + it("returns the board's refusal as an error", async () => { const { run, fileItem } = await setup({ transition: async request => ({ diff --git a/mastracode/factory/src/tools/work-item-tools.ts b/mastracode/factory/src/tools/work-item-tools.ts index eb7589c58e1..382c1fd334e 100644 --- a/mastracode/factory/src/tools/work-item-tools.ts +++ b/mastracode/factory/src/tools/work-item-tools.ts @@ -132,7 +132,7 @@ export function createFactoryWorkItemTools( : `${slug} is not linked to this Factory, and it has no linked repositories.`, ); }; - const follow = (item: Card, reason: 'created' | 'subscribed') => + const follow = (item: Card, reason: 'created' | 'moved' | 'subscribed') => deps.workItems.subscribeToWorkItem({ ...project, workItemId: item.id, @@ -232,7 +232,21 @@ export function createFactoryWorkItemTools( }), }); if (result.status === 'rejected') throw new Error(`The move was refused (${result.code}): ${result.reason}`); - return { workItemId: item.id, stage: result.stage, revision: result.revision }; + // The move can start a phase session the Factory owns. Following the card is what lets + // this session hear when that run waits on someone, and answer it from here. + // The card has moved by now: a failed follow is reported with the move, not instead of it. + const moved = { workItemId: item.id, stage: result.stage, revision: result.revision }; + try { + await follow(item, 'moved'); + } catch (error) { + return { + ...moved, + warnings: [ + `This session does not follow it yet: ${error instanceof Error ? error.message : String(error)}`, + ], + }; + } + return moved; }, }), diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 1a8ef499aa0..4e6269e89dc 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -2491,6 +2491,9 @@ importers: specifier: 'catalog:' version: 4.6.7 devDependencies: + '@copilotkit/aimock': + specifier: ^1.46.0 + version: 1.47.0(vitest@5.1.0) '@internal/lint': specifier: workspace:* version: link:../../packages/_config From 9411a9dcd65ffff4987d868e4cfde4b5b10cf2aa Mon Sep 17 00:00:00 2001 From: "mastra-platform[bot]" <284800079+mastra-platform[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:01:11 +0000 Subject: [PATCH 013/239] fix(factory-ui): remove "Move across the factory" hint from sign-in visual (#30256) > Opened by @DSchau ## Summary Removes the faint "Move across the factory" label (and its leading rule) from the halftone panel on the Factory sign-in page. All it did was point at a cosmetic hover effect (dots under the cursor take on the lane color), so it looked like unexplained clutter. The hover spotlight still works. - `FactoryHalftoneField.tsx`: drop the hint element and update the doc comment - `sign-in-page.css`: drop the now-unused `.factory-visual-hint` rule ## Test plan - `tsc --noEmit -p src/ui/tsconfig.json` in `mastracode/factory-ui` passes - The sign-in page panel still shows the stage labels and the hover spotlight, with no hint in the bottom-right ELI5: The sign-in page had a small text hint, "Move across the factory," with a short line in front of it. The hint described a hover effect that is still there. This change removes the hint and its line, so the page shows less text. ## Summary This pull request removes the "Move across the factory" hint from the Factory sign-in visual panel. The hover spotlight and stage labels remain. ## Changes - `mastracode/factory-ui/src/ui/domains/auth/components/FactoryHalftoneField.tsx` - Updates the doc comment for the `panel` variant. It no longer mentions the hint. - Removes the `` element that rendered "Move across the factory". This element used the `factory-visual-hint` class and was positioned at the bottom-right of the panel. - The `` element and the stage labels are unchanged. - `mastracode/factory-ui/src/ui/domains/auth/components/sign-in-page.css` - Removes the `.factory-visual-hint::before` rule. This rule drew a 1.375rem horizontal line before the hint. ## Scope - 2 files changed. - 1 line added and 16 lines removed. - No exported or public declarations changed. - Tests and type-check results: not available. Co-authored-by: mastra-platform[bot] Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> --- .../domains/auth/components/FactoryHalftoneField.tsx | 10 +--------- .../src/ui/domains/auth/components/sign-in-page.css | 7 ------- 2 files changed, 1 insertion(+), 16 deletions(-) diff --git a/mastracode/factory-ui/src/ui/domains/auth/components/FactoryHalftoneField.tsx b/mastracode/factory-ui/src/ui/domains/auth/components/FactoryHalftoneField.tsx index 37237198fa1..2ea50388bfa 100644 --- a/mastracode/factory-ui/src/ui/domains/auth/components/FactoryHalftoneField.tsx +++ b/mastracode/factory-ui/src/ui/domains/auth/components/FactoryHalftoneField.tsx @@ -65,7 +65,7 @@ function densityAt(lane: number, laneProgress: number, verticalProgress: number, * lanes (Intake → Build → Review → Ship). * * - `panel` (default): the full sign-in visual — a bordered side panel with - * stage labels, a hover spotlight and the "move across the factory" hint. + * stage labels and a hover spotlight. * - `backdrop`: the same animated field with the chrome stripped, sized to fill * its positioned parent and faded toward the center so foreground content * stays legible. Used behind the Factory onboarding flow. @@ -278,14 +278,6 @@ export function FactoryHalftoneField({ variant = 'panel' }: { variant?: 'panel'