Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
9eb2335
2026-10-29-2038-register-roster-redirect-domains: shaped
jayjfletcher Oct 29, 2026
d836224
2026-10-29-2038-register-roster-redirect-domains: shaping decisions
jayjfletcher Oct 29, 2026
6cbefe0
2026-10-29-2038-register-roster-redirect-domains: every screen declar…
jayjfletcher Oct 29, 2026
b647572
2026-10-29-2038-register-roster-redirect-domains: no package knows an…
jayjfletcher Oct 29, 2026
6456508
2026-10-29-2038-register-roster-redirect-domains: spec written
jayjfletcher Oct 30, 2026
87593f4
2026-10-29-2038-register-roster-redirect-domains: approved: decisions…
jayjfletcher Oct 30, 2026
570ac86
2026-10-29-2038-register-roster-redirect-domains: building (run 2)
jayjfletcher Oct 30, 2026
755914b
2026-10-29-2038-register-roster-redirect-domains: group 1 Owner-decid…
jayjfletcher Oct 30, 2026
2c25a5a
2026-10-29-2038-register-roster-redirect-domains: group 2 Composer, a…
jayjfletcher Oct 30, 2026
6b56c5d
2026-10-29-2038-register-roster-redirect-domains: group 1 Owner-decid…
jayjfletcher Oct 30, 2026
98345d9
Merge ring-master/2026-10-29-2038-register-roster-redirect-domains--g1
jayjfletcher Oct 30, 2026
5c0051a
Merge ring-master/2026-10-29-2038-register-roster-redirect-domains--g2
jayjfletcher Oct 30, 2026
361dd94
Integrate wave 1: tick groups 1 and 2
jayjfletcher Oct 30, 2026
2f49607
2026-10-29-2038-register-roster-redirect-domains: group 3 Redirect do…
jayjfletcher Oct 30, 2026
1f6a976
2026-10-29-2038-register-roster-redirect-domains: group 4 Declare Cor…
jayjfletcher Oct 30, 2026
c9343bf
2026-10-29-2038-register-roster-redirect-domains: group 3 Redirect do…
jayjfletcher Oct 30, 2026
a08a977
2026-10-29-2038-register-roster-redirect-domains: group 4 Declare Cor…
jayjfletcher Oct 30, 2026
160f8ad
Merge ring-master/2026-10-29-2038-register-roster-redirect-domains--g3
jayjfletcher Oct 30, 2026
2b40b81
Merge ring-master/2026-10-29-2038-register-roster-redirect-domains--g4
jayjfletcher Oct 30, 2026
6e0e253
2026-10-29-2038-register-roster-redirect-domains: integrate wave 1
jayjfletcher Oct 30, 2026
9c74c52
2026-10-29-2038-register-roster-redirect-domains: group 5 README and …
jayjfletcher Oct 30, 2026
94ad8da
2026-10-29-2038-register-roster-redirect-domains: group 5 README and …
jayjfletcher Oct 30, 2026
8d82917
2026-10-29-2038-register-roster-redirect-domains: rework round 1
jayjfletcher Oct 30, 2026
9f1b8e5
Record factory run
jayjfletcher Oct 30, 2026
e15cbb7
Record PR
jayjfletcher Oct 30, 2026
8f9c5a5
Fix the without-Atrium CI job
jayjfletcher Oct 30, 2026
af79593
Fix NoHistoryUiTest on Windows: compare forward-slash paths
jayjfletcher Oct 30, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,45 @@ jobs:
- name: Test Suite (Windows)
if: runner.os == 'Windows'
run: vendor/bin/pest

# The authoritative no-Atrium proof: Atrium is uninstalled, so no classmap or
# Composer `files` entry can reach it, as the in-process suite cannot see.
without-atrium:
runs-on: ubuntu-latest

name: P8.5 - L13.* - without Atrium

steps:
- name: Checkout code
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Setup PHP
uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # v2
with:
php-version: 8.5
extensions: dom, curl, libxml, mbstring, zip, fileinfo, sqlite, pdo_sqlite, bcmath, intl
ini-values: error_reporting=E_ALL
tools: composer:v2
coverage: none

# testbench.yaml loads Atrium's provider for the workbench; Testbench's
# package:discover (run by Composer's scripts) dies on it once Atrium is gone.
- name: Drop Atrium from the Testbench providers
run: sed -i '/RefactorCircus\\Atrium\\AtriumServiceProvider/d' testbench.yaml

- name: Remove Atrium
run: composer remove --dev refactor-circus/atrium --no-update --no-interaction

- name: Install dependencies
run: |
composer update --prefer-stable --prefer-dist --no-interaction --no-progress --no-scripts
composer run prepare

- name: Dump autoloader
run: composer dump-autoload

- name: Atrium is not installed
run: test ! -e vendor/refactor-circus/atrium

- name: Test Suite without Atrium
run: composer test:without-atrium
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Atrium owns every component and style; Cortex ships no `resources/css`, no `Atri

- Views use only `x-atrium::*` components and the utilities Atrium safelists. No `<style>` blocks and no `style=` attributes. `tests/Feature/Ui/StylesTest.php` checks this with `RefactorCircus\Atrium\Testing\AtriumStyles`.
- Status and errors use `<x-atrium::flash :keys="['prompt', 'agent']" />`; tag filters are `x-atrium::chip`s; searches are `x-atrium::search-input`.
- History is `<x-atrium::audit-trail source="cortex" />`, with `:subject` on a record's screen. The content-versions partial stays, since versions are publishable content.
- Every page with a controller view declares a standard Atrium screen with `Atrium\Screens::declare($key, $kind, $record, $subject)` (keys `cortex.*`), resolves it with `ScreenExtensions::resolve()` after its own authorization and renders `x-atrium::screen-tabs`, `x-atrium::screen-tab-panel` and every slot it declares, as Atrium's own screens do. Cortex has no history UI: no history slot, audit subject or audit component, and no history navigation item (History is Keen's, attached by wildcard). The content-versions partial stays, since versions are publishable content.
- `CortexPlugin::features()` uses Atrium's `featuresFromConfig()`. Cortex keeps its own `Atrium\ScreenAccess` and `AuthorizesScreens`: Atrium's copies follow Keystone's `authorization` switch and refuse guests, while Cortex asks the Gate as the signed-in user or as a guest, with extra arguments.

## Quick Commands
Expand All @@ -59,4 +59,5 @@ Atrium owns every component and style; Cortex ships no `resources/css`, no `Atri
- Specs, product docs and local standards live in `docs/agent/`. Shared standards come from `vendor/` through `docs/agent/standards.index.yml`; read the matching standards before changing code.
- Workflow: `/ring-master-shape-spec` → `/ring-master-write-spec` → `/ring-master-create-tasks` → `/ring-master-implement` → `/ring-master-verify-spec`.
- Done means `composer test` passes. When work must break a standard, add a row to `docs/agent/standards-feedback.md`.
- Keep this checkout on `main`: other packages' jobs build against it. Never switch branches, commit or stash here; do any change that is not a factory job (which makes its own) in a worktree beside the package: `git worktree add ../<Package>--<slug> -b <branch> origin/main`, removed once it is merged.
<!-- ring-master:end -->
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,20 @@
- **Run `composer dump-autoload -o`** after updating (and regenerate any pre-built or classmap-authoritative `vendor/`): the deprecated aliases of the renamed classes load through a new `autoload.files` entry, and without it the old class names are not found.
- **Drain your queues and re-register listeners** before upgrading: events, actions, Data objects, requests and exceptions of the old `Domains\McpServer` namespace moved without aliases (see Breaking).

### Upgrade notes (Atrium screens and owned redirect domains)

- **Grouped merge.** This change ships together with refactor-circus/atrium (the screen-extensions registry, which also removes Atrium's audit-trail components), refactor-circus/keen and refactor-circus/roster. Merge and upgrade all four at once: with only some of them upgraded, Roster's MCP tab disappears.
- **Atrium is suggested, not required.** `refactor-circus/atrium` moved from `require` to `require-dev`, and is listed under `suggest`. Apps that use the Cortex dashboard or its redirect-domain screens must run `composer require refactor-circus/atrium` themselves. Without Atrium the dashboard and those screens are absent, with no error and no log entry, and the JSON API and MCP keep working. A new Composer `conflict` refuses Atrium versions older than the screen registry (`<0.1.0`), so a mismatched install fails at `composer update`.
- **New config key `cortex.atrium.redirect_domains.screens`.** It puts the redirect-domain tab (`cortex.mcp`) or section (`cortex.redirect-domains`) on other packages' screens. It defaults to `['roster.organization' => 'tab', 'roster.user' => 'aside']`. A config published before this release has no `redirect_domains` key under `atrium` and gets that default; set it to `[]` to show the domains on no screen. A malformed entry throws `InvalidArgumentException` at boot in `local` and `testing`, and is reported and skipped in every other environment.
- **Owner fields on the dashboard's redirect-domain routes.** `atrium.cortex.redirect-domains.store` and `atrium.cortex.redirect-domains.destroy` accept optional `owner_type` (a morph alias or model class that `RedirectDomains::owner()` resolves) and `owner_id`. Send both or neither; one alone is a validation error. With an owner, the routes redirect to the previous page when it is on the same scheme, host and port, and to the redirect-domains screen otherwise. Without an owner nothing changes.
- **Owned redirect domains ask the owner (behaviour change).** For a domain with an owner, the bundled `RedirectDomainPolicy` now allows `create` and `delete` only to a signed-in user who may `update` the owner (`$user->can('update', $owner)`). This applies on the dashboard, over the JSON API and over MCP:
- Guests and users without `update` on the owner are refused: 401 for a guest and 403 for a signed-in user over the JSON API, and refused over MCP. Nothing is written or removed.
- A domain whose owner row no longer exists cannot be deleted through the bundled policy.
- An owner model with no policy and no `update` ability denies it. Apps that used owned domains without an owner policy must add one, or point `RedirectDomainModel` at their own class in `cortex.policies`; an app that already does is unaffected.
- Domains without an owner are unchanged, and `viewAny` still allows everyone.
- **History UI removed.** Cortex's pages no longer render Atrium's audit-trail component, and the **Audit log** link in Cortex's sidebar group is gone. History is now provided by refactor-circus/keen, which adds it to Cortex's declared Atrium screens (`cortex.*` keys). `GET /cortex/history` and `list-cortex-history-tool` are unchanged.
- **Roster's MCP tab is now Cortex's.** The tab on Roster's organization page changes from `?tab=mcp` to `?tab=cortex.mcp`. Old `?tab=mcp` links open the page's default tab. Roster's own redirect-domain route names are gone; the forms post to Cortex's `atrium.cortex.redirect-domains.*` routes.

### Breaking

- **The `McpServer` domain is now `ConcreteServer`.** Every class moved from `RefactorCircus\Cortex\Domains\McpServer\...` to `RefactorCircus\Cortex\Domains\ConcreteServer\...` with its name unchanged, and `McpServerServiceProvider` is now `ConcreteServerServiceProvider`. Table names, route URIs and names, MCP tool names, config keys and registered server names are unchanged. Polymorphic columns and audit entries keep storing the old model class names, which a morph map resolves to the new models; a host that calls `Relation::enforceMorphMap()` or `Relation::morphMap([...], false)` must keep the two `Domains\McpServer\Models\...` keys, and must not map the two models under another alias. Cortex logs a warning after boot when either key is lost or re-mapped.
Expand Down
58 changes: 52 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,15 @@ Publish the config file to customize routes, the dashboard, MCP transports, and
php artisan vendor:publish --tag="cortex-config"
```

The dashboard renders through Atrium, so publish its assets too:
The dashboard renders through [Atrium](https://github.com/refactor-circus/atrium), which Cortex suggests but does not require. To use the dashboard, require Atrium and publish its assets:

```bash
composer require refactor-circus/atrium
php artisan vendor:publish --tag="atrium-assets"
```

Without Atrium, Cortex has no dashboard, and its JSON API and MCP server work as usual. See [Redirect domains on other screens](#redirect-domains-on-other-screens).

## Configuration

```php
Expand Down Expand Up @@ -100,15 +103,15 @@ return [

Every API endpoint and MCP tool that touches a model checks it through the Gate, using the policies in `cortex.policies`. It checks as the signed-in user, or as a guest when nobody is signed in. Listing or creating checks `viewAny` or `create` against the model class. Reading, changing, deleting, publishing or running checks `view`, `update`, `delete`, `publish` or `run` against the record.

Cortex records have no owner, so the bundled policies allow everything and your middleware stays the gate, as before. Version policies defer to their virtual agent or override through the Gate: reading a version needs `view` on it, adding or publishing one needs `update`. Point a model at your own policy class in `cortex.policies` to restrict it.
Cortex records have no owner, so the bundled policies allow everything and your middleware stays the gate, as before. Redirect domains are the exception: adding or removing one that belongs to an owner, such as an organization, asks `update` on that owner (see [who may manage an owner's domains](#redirect-domains-on-other-screens)). Version policies defer to their virtual agent or override through the Gate: reading a version needs `view` on it, adding or publishing one needs `update`. Point a model at your own policy class in `cortex.policies` to restrict it.

Changing a concrete MCP server's tool list checks its own ability, `updateTools`, which the bundled policy allows for guests too. Read [who may change a server's tools](#who-may-change-a-servers-tools) before exposing the routes.

**Full guide:** [Policies](docs/policies.md). It covers what each endpoint and MCP tool checks, and how to replace a policy.

## Dashboard

Cortex renders its dashboard through [Atrium](https://github.com/refactor-circus/atrium), which it requires. Install Atrium's gate and Cortex appears in the sidebar automatically:
Cortex renders its dashboard through [Atrium](https://github.com/refactor-circus/atrium). Atrium is suggested, not required: require `refactor-circus/atrium` to get the dashboard. Without it there is no dashboard, and nothing reports its absence. Install Atrium's gate and Cortex appears in the sidebar automatically:

```php
use Illuminate\Support\Facades\Gate;
Expand All @@ -133,7 +136,7 @@ The screens follow Atrium's screen conventions: actions are icon buttons with th

Cortex ships no stylesheet and no components of its own: its views use Atrium's components (`search-input`, `chip`, `flash`, form controls, tables, cards) and the utilities Atrium compiles. A test asserts it with `RefactorCircus\Atrium\Testing\AtriumStyles`.

With an audit log such as [refactor-circus/keen](https://github.com/Refactor-Circus/Keen) installed, the screens show history through Atrium's `<x-atrium::audit-trail>`: the virtual agents list shows all of Cortex's, and a virtual agent, a tool description, an MCP server instruction or a concrete agent override shows its own, below its versions. Without an audit log nothing is shown.
Every page declares itself as an Atrium screen (`cortex.virtual-agents`, `cortex.virtual-agent`, `cortex.tools`, `cortex.redirect-domains` and so on), so other packages can add tabs and sections to it through `Atrium::screens()` without Cortex knowing them. Cortex shows no history of its own: an audit log such as [refactor-circus/keen](https://github.com/Refactor-Circus/Keen) adds History to the screens itself.

To switch Cortex in the dashboard on and off as a whole - navigation, search, settings and pages, which answer `404` while it is off - install [refactor-circus/pennantplus](https://github.com/Refactor-Circus/PennantPlus). `RefactorCircus\Cortex\Atrium\Features\CortexSupportFeature` is on until its global value is set, and only its global value counts:

Expand Down Expand Up @@ -433,9 +436,52 @@ laravel/mcp's dynamic client registration (`Mcp::oauthRoutes()`) only accepts re
- **API and MCP:** `/cortex/redirect-domains` and the `list-redirect-domains-tool`, `create-redirect-domain-tool` and `delete-redirect-domain-tool` tools.
- **Code:** `app(CreateRedirectDomainAction::class)->execute(new CreateRedirectDomainData('claude.ai'), $owner)`.

A domain may belong to any model, such as an organization or a user (Roster manages them on its organization and user pages), or to no one. Hosts, origins and full redirect URLs are all stored as their origin: `claude.ai`, `https://claude.ai/` and `https://claude.ai/api/mcp/auth_callback` are all `https://claude.ai`. Only config can allow `*`.
A domain may belong to any model, such as an organization or a user, or to no one. Cortex shows an owner's domains on that owner's own screens, such as Roster's organization and user pages (see [Redirect domains on other screens](#redirect-domains-on-other-screens)). Hosts, origins and full redirect URLs are all stored as their origin: `claude.ai`, `https://claude.ai/` and `https://claude.ai/api/mcp/auth_callback` are all `https://claude.ai`. Only config can allow `*`.

Registration is anonymous, so every client may register on every allowed origin, whoever added it; the owner says who manages a domain, not who may use it. Users still approve each client on the consent screen. The configured domains, `*` and localhost keep working as laravel/mcp documents. Set `cortex.redirect_domains.enabled` to `false` to use the configured domains alone. The policy in `cortex.policies` receives the owner on `create`. For a domain with an owner, the bundled policy lets only a user who may `update` the owner add or remove it, so the owner's own policy decides.

### Redirect domains on other screens

Cortex shows an owner's redirect domains on other packages' Atrium screens, such as Roster's organization and user pages, so they are managed where the owner is. Which screens get them is set in `cortex.atrium.redirect_domains.screens`:

```php
// config/cortex.php
'atrium' => [
'redirect_domains' => [
'screens' => [
'roster.organization' => 'tab',
'roster.user' => 'aside',
],
],
],
```

- **Keys** are Atrium screen keys. The screen's record is the owner of the domains shown.
- **`tab`** adds the `cortex.mcp` tab, labelled "MCP" and opened with `?tab=cortex.mcp`.
- **Any other value** names the slot that gets the `cortex.redirect-domains` section, such as `aside`, `before`, `after` or `header.actions`.
- **`[]`** puts the domains on no screen.
- **No key.** A config published before this key existed has no `redirect_domains` entry under `atrium`, and gets the default map above.
- **Undeclared screens.** A screen that no installed package declares shows nothing, so the defaults are harmless without Roster.

The tab or section is shown only when all of these hold:

- stored redirect domains are on (`cortex.redirect_domains.enabled`)
- the screen's record is a saved Eloquent model
- Cortex is on in Atrium for the request: `cortex.ui.enabled` is true and every feature in `cortex.atrium.features` is on
- the viewer passes `viewAny` on `RedirectDomainModel` with the owner

A policy that throws is reported and hides the tab or section; it never breaks the host page. The panel lists the owner's domains. The add form shows to viewers who pass `create` with the owner, and the remove button shows on each domain the viewer may `delete`. The forms post `owner_type` (the owner's morph class) and `owner_id` to Cortex's `atrium.cortex.redirect-domains.store` and `atrium.cortex.redirect-domains.destroy` routes. Afterwards they go back to the host page when it is on the same scheme, host and port, and to Cortex's redirect-domains screen otherwise.

**Who may manage an owner's domains.** For a domain with an owner, the bundled `RedirectDomainPolicy` allows `create` and `delete` only to a signed-in user who may update the owner, `$user->can('update', $owner)`, so the owner's own policy decides. This applies on the screens, over the JSON API and over MCP. Guests are refused. So is a domain whose owner row is gone, and an owner model with no policy and no `update` ability. Domains without an owner are unchanged, and everyone may still add and remove them. To decide otherwise, point `RedirectDomainModel` at your own policy class in `cortex.policies`.

**Malformed entries.** An entry is malformed when its value is not a string, is empty, or names a screen key or slot that Atrium rejects. In the `local` and `testing` environments it throws `InvalidArgumentException` at boot. In every other environment, production included, it is reported once with `report()` and skipped; the other entries still register and the application keeps booting. Until the report is acted on, that screen has no redirect domains.

**Atrium is suggested, not required.** Cortex lists `refactor-circus/atrium` under `suggest` in its `composer.json`. Without Atrium, the dashboard and these screens are simply absent: there is no error and no log entry, and the JSON API and MCP server keep working. Atrium versions older than its screen registry are refused through a Composer `conflict` (`<0.1.0`), so a mismatched install fails at `composer update` rather than at runtime.

Cortex's test suite proves it runs without Atrium in two ways:

Registration is anonymous, so every client may register on every allowed origin, whoever added it; the owner says who manages a domain, not who may use it. Users still approve each client on the consent screen. The configured domains, `*` and localhost keep working as laravel/mcp documents. Set `cortex.redirect_domains.enabled` to `false` to use the configured domains alone. The policy in `cortex.policies` receives the owner on `create`, so an application can let an organization's admins manage only that organization's domains.
- `composer test:without-atrium`, part of `composer test`, runs in process with Atrium's classes removed from the autoloader. It cannot catch an Atrium class reached through a classmap or a Composer `files` entry.
- The `without-atrium` CI job uninstalls Atrium and runs the same suite. This CI lane is the authoritative proof.

## Events

Expand Down
Loading
Loading