Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
d1edd5c
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 1 Rename McpS…
jayjfletcher Oct 24, 2026
7242415
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 2 Class-name …
jayjfletcher Oct 25, 2026
13fb9a3
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 10 Morph aliases
jayjfletcher Oct 25, 2026
0a78577
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 11 Policy-key…
jayjfletcher Oct 25, 2026
3443e0d
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 12 Keen and C…
jayjfletcher Oct 25, 2026
9dbb2ba
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 3 Tools colum…
jayjfletcher Oct 25, 2026
7e04d78
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 3 Tools colum…
jayjfletcher Oct 25, 2026
1385757
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 4 Update, cle…
jayjfletcher Oct 25, 2026
3f708e5
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 5 Serving the…
jayjfletcher Oct 25, 2026
627306c
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 6 HTTP and MC…
jayjfletcher Oct 25, 2026
e830c2f
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 6 HTTP and MC…
jayjfletcher Oct 25, 2026
034150a
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 7 Atrium tool…
jayjfletcher Oct 25, 2026
a08199e
2026-10-23-1917-virtual-and-concrete-mcp-servers: group 8 Renamed tab…
jayjfletcher Oct 25, 2026
be226ed
2026-10-23-1917-virtual-and-concrete-mcp-servers: rework round 2
jayjfletcher Oct 25, 2026
f63ef9b
2026-10-23-1917-virtual-and-concrete-mcp-servers: rework round 1
jayjfletcher Oct 26, 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
5 changes: 5 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,11 @@ jobs:
composer update --${{ matrix.stability }} --prefer-dist --no-interaction --no-progress --no-scripts
composer run prepare

# Regenerates the autoloader so vendor/composer/autoload_files.php lists the
# src/Domains/ConcreteServer/shims.php compatibility shim before any test runs.
- name: Dump autoloader
run: composer dump-autoload

- name: PHPStan
if: runner.os != 'Windows'
run: composer analyse
Expand Down
12 changes: 10 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ This repository is a Laravel package. Keep the package focused, idiomatic, and e

## Layout

The package follows the mono domain-module layout, described in `agent-os/standards/backend/domain-modules.md`. Code lives in `src/Domains/{VirtualAgent,ConcreteAgent,Tool,McpServer,RedirectDomain}` (namespace `RefactorCircus\Cortex\Domains\{Domain}`), each with its own `{Domain}ServiceProvider` registered by `Domains\DomainServiceProvider`. Models are named `{Entity}Model`. The Atrium screens span every domain and live in `src/Atrium`; package-wide pieces (`Cortex`, the facade, the base requests, `Mcp\CortexServer`, `Support\`) stay at the top level. `config/cortex.php` stays one file.
The package follows the mono domain-module layout, described in `agent-os/standards/backend/domain-modules.md`. Code lives in `src/Domains/{VirtualAgent,ConcreteAgent,Tool,ConcreteServer,RedirectDomain}` (namespace `RefactorCircus\Cortex\Domains\{Domain}`), each with its own `{Domain}ServiceProvider` registered by `Domains\DomainServiceProvider`. Models are named `{Entity}Model`. The Atrium screens span every domain and live in `src/Atrium`; package-wide pieces (`Cortex`, the facade, the base requests, `Mcp\CortexServer`, `Support\`) stay at the top level. `config/cortex.php` stays one file.

## Keystone

Expand All @@ -24,7 +24,7 @@ Cortex stands on `refactor-circus/keystone`, the shared runtime of the Refactor
- Action input is a `final readonly` `{Action}Data` in the domain's `Data/` (on `RefactorCircus\Keystone\Data\Data`), never an array: fields are promoted constructor properties (camelCase of the input keys; `T|Missing = new Missing` for partial updates), `rules()` lives on the Data (with any context args, e.g. `UpdateConcreteAgentToolsData::rules($agent)`), and the starting/finished events that took input carry the Data. List Data expose `pagination()` (Keystone's `Pagination`) and add its rules; their tools add `ListXData::pagination()->schema($schema)`. HTTP and MCP requests validate once: their `rules()` return the identifier rules (`agentRules()`, `versionRules()`, `serverRules()`, `ownerRules()`, `domainRules()` on the MCP and redirect-domain bases) plus `XData::rules(...)`, and `persist()`/`handle()` build with `XData::fromValidated($this->validated() / $validated)` - never `XData::from()` in a request (ArchTest). Atrium controllers use `XData::from($request->all(), ...context)`, which validates; code that vouches for its values uses `new XData(...)`.
- API resources extend `RefactorCircus\Keystone\Http\Resources\JsonResource` and declare `schema(JsonSchema $schema)` next to `toArray()` (always-present fields `required()`, conditional ones not, `nullable()` where null is possible). MCP requests answer with `(new XResource($m))->toStructuredResponse()` / `XResource::collection($page)->toStructuredResponse()`, and each tool that answers with structured content declares `outputSchema()` as `XResource::structuredSchema($schema)` / `collectionSchema($schema, ListXData::pagination())` (unpaginated lists declare `data` alone). `mcpTool()` in tests is Keystone's `Testing\McpTools::call()`, which checks every structured answer against the tool's schema, and `tests/Feature/Mcp/OutputSchemaTest.php` requires the declaration.
- `Http\Request` and `Mcp\Request` extend Keystone's request bases but keep Cortex's authorization: every check goes to the Gate, as the signed-in user or as a guest, and the bundled policies allow guests. Do not switch them to Keystone's `authorization` switch. A guest refused over HTTP gets 401 (Keystone's base), a signed-in user 403. `ConcreteAgentMcpRequest` and `ServerMcpRequest` throw `ModelNotFoundException` for unknown names on purpose, so they answer the base request's `Not found.`.
- `Mcp\CortexServer` extends `RefactorCircus\Keystone\Mcp\Server` and lists every tool in `TOOLS`, including `Mcp\Tools\ListCortexHistoryTool`. Cortex's own tools extend `RefactorCircus\Keystone\Mcp\Tool`; `Domains\Tool\Support\Tool` and `Domains\McpServer\Support\Server` are for application tools and servers.
- `Mcp\CortexServer` extends `RefactorCircus\Keystone\Mcp\Server` and lists every tool in `TOOLS`, including `Mcp\Tools\ListCortexHistoryTool`. Cortex's own tools extend `RefactorCircus\Keystone\Mcp\Tool`; `Domains\Tool\Support\Tool` and `Domains\ConcreteServer\Support\Server` are for application tools and servers.

## Frontend

Expand All @@ -51,3 +51,11 @@ Atrium owns every component and style; Cortex ships no `resources/css`, no `Atri
- `package-release`: use when preparing changelog, release notes, tags, or GitHub release workflow changes.
- `package-compatibility`: use when reviewing code, dependencies, or CI against the PHP and Laravel support matrix.
- `package-generate-skill`: use when updating the bundled Boost skill from the package implementation, README, and examples.

<!-- ring-master:start -->
## Ring Master

- 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 `vendor/bin/pest` passes. When work must break a standard, add a row to `docs/agent/standards-feedback.md`.
<!-- ring-master:end -->
20 changes: 20 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,29 @@

## [Unreleased](https://github.com/Refactor-Circus/Cortex/commits/main)

### Upgrade notes (security-relevant)

- **New routes and MCP tools that change an MCP server's tool list are live as soon as you upgrade.** `PUT /cortex/servers/{server}/tools`, `DELETE /cortex/servers/{server}/tools`, the `update-server-tools-tool` and `clear-server-tools-tool` MCP tools and the dashboard's tool editor check the new `updateTools` ability, and the bundled `McpInstructionPolicy` allows it **for guests too**, like every other bundled ability. The routes share the existing server routes' group and middleware, with no switch of their own. Whoever passes `updateTools` can put any registered Cortex tool (`Laravel\Ai` tools included) on a registered server, in front of every MCP client of that server; no per-tool ability is checked. Before deploying, point `McpInstructionModel` in `cortex.policies` at a policy whose `updateTools` denies by default (snippet in the README, "Who may change a server's tools") or make sure your route middleware keeps guests out. Outside the `local` environment Cortex logs a warning at boot, once per worker process, naming the servers whose tools guests may change.
- A host policy for `McpInstructionModel` that has no `updateTools` method denies it (the Gate's default): the tool routes answer 403 to a signed-in user and 401 to a guest, the MCP tools refuse and the dashboard shows the tools read-only. Add the method to use the feature.
- **Run the new migration.** Tool overrides live in a new nullable `tools` column on `cortex_mcp_instructions` (`2026_10_23_000002_add_tools_to_cortex_mcp_instructions`). Publish the migrations with `php artisan vendor:publish --tag="cortex-migrations"` and run `php artisan migrate`. If you already published Cortex's migrations, copy just that file from `vendor/refactor-circus/cortex/database/migrations` instead of publishing the tag again, which re-stamps every migration and makes `migrate` fail on existing tables; the migration skips a column that already exists. Until it runs, servers serve their code tools and Cortex logs a rate-limited warning naming the migration. The column check is remembered per process, so restart Octane and queue workers after migrating. Rolling the migration back drops the column and every stored tool override.
- **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).

### 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.
- **Events, actions, Data objects, requests and exceptions moved without aliases.** Only the classes listed under Deprecated keep their old names. A listener registered by an old event class name (`Event::listen`, a subscriber, a `$listen` map) stops hearing the event without an error, a `catch` of an old exception stops matching, a type-hint or binding of an old action breaks, and queued jobs or listeners serialized with an old class name fail to unserialize. Re-register listeners by the new class names and drain queues before upgrading. Asking for one of these old names logs a warning naming its new class, then fails as class not found.
- **`DELETE /cortex/servers/{server}/instructions` and `delete-server-instructions-tool` keep a tool override.** They delete the instruction versions and the published pointer, and remove the override row only when it holds no tool override. When there is none the answer is as before: 204 and a text answer over MCP. When the server has a tool override the row stays and the tools are still served, and the route now answers **200 with the server's instructions resource** (`tools_overridden: true`), the MCP tool that resource as structured content. Clear the tools with the new `DELETE /cortex/servers/{server}/tools`. The versions are deleted one model at a time, so each fires its own `McpInstructionVersionDeleting/DeletedEvent` (at least once: they fire inside the transaction, so a rolled-back delete has already fired them) and a long history means as many deletes in one transaction. With refactor-circus/keen installed the delete writes one `mcp_instruction.deleted` audit entry; the per-version deletes show only as model events.

- Moved to the Refactor Circus organisation: the package is now `refactor-circus/cortex` with the PHP namespace `RefactorCircus\Cortex` (it was `jayi/cortex` and `JayI\Cortex`). Update `composer.json` requirements and `use` statements. Old class names are not kept as aliases, so stored values written under them - polymorphic `*_type` columns, audit subjects, Pennant feature names - need updating to the new names.
- **Actions take their input as Data objects instead of arrays.** Every Action that took an input array, a toolset list, a run input, a tag or a page now takes a typed, immutable `{Action}Data` from its domain's `Data` namespace, built on refactor-circus/keystone's `Data`: `CreateVirtualAgentData`, `UpdateVirtualAgentData`, `CreateVirtualAgentVersionData`, `ListVirtualAgentsData`, `ListVirtualAgentVersionsData`, `RunVirtualAgentData`, `CreateConcreteAgentVersionData`, `UpdateConcreteAgentToolsData`, `RunConcreteAgentData`, `CreateToolDescriptionVersionData`, `ListToolsData`, `CreateMcpInstructionVersionData` and `CreateRedirectDomainData`. Build one from untrusted input with `XData::from($input)`, which validates it (throwing `ValidationException`) and casts each snake_case key to its typed field; from input already validated against `XData::rules()` with `XData::fromValidated($validated)`; from your own values with `new XData(...)`, e.g. `app(CreateRedirectDomainAction::class)->execute(new CreateRedirectDomainData('claude.ai'), $owner)`. `Action::rules()` moved to `XData::rules()` (`UpdateConcreteAgentToolsData::rules($agent)` keeps its agent argument), and Actions without input lost their empty `rules()`. `UpdateVirtualAgentData` leaves fields out as `Keystone\Data\Missing`, so a field set to null stays apart from one not sent. Action events that carried the input (`VirtualAgentCreatingActionEvent::$data`, `ConcreteAgentToolsUpdatingActionEvent::$tools`, `VirtualAgentsListingActionEvent::$page`, `ToolsListingActionEvent::$tag`, the running and ran events' `$input`, ...) carry the Data object as `$data` or `$filters`.
- **Structured MCP answers carry the resource under `data`.** Tools that answer with one record (show, create, update, publish, run) now answer `{"data": {...}}`, as the JSON API does, instead of the bare record; lists keep their `data` envelope, and the paginated virtual agent and version lists add a `meta` with the page.

### Deprecated

- The old names of `Support\Server`, `Concerns\HasVersionedInstructions`, `Models\McpInstructionModel`, `Models\McpInstructionVersionModel`, `Policies\McpInstructionPolicy` and `Policies\McpInstructionVersionPolicy` under `RefactorCircus\Cortex\Domains\McpServer\` still load, as aliases of the `ConcreteServer` classes registered lazily (only when an old name is asked for) through `src/Domains/ConcreteServer/shims.php` in `autoload.files`. They are removed in the next major release; move your references to `RefactorCircus\Cortex\Domains\ConcreteServer\...`.
- `cortex.policies` keys naming an old model class are moved to the new class, keeping your policy, with a deprecation warning per key; when both keys are listed the new one wins. Key the entries by the new model classes.

### Changed

- **MCP output schemas.** Every tool that answers with structured content declares an `outputSchema()`, built from its resource's new `schema()` (fields, types and nullability), so agents know the shape before calling. Every resource extends refactor-circus/keystone's `JsonResource` and answers MCP calls with `toStructuredResponse()`.
Expand All @@ -19,6 +36,9 @@

### Added

- **Concrete server tool overrides.** A registered MCP server's tool list can be replaced without a deploy, picked from its code-declared tools and the registered Cortex tools: `PUT /cortex/servers/{server}/tools` (`cortex.servers.tools.update`) and the `update-server-tools-tool` MCP tool set it, `DELETE /cortex/servers/{server}/tools` (`cortex.servers.tools.destroy`) and `clear-server-tools-tool` clear it, and the server screen has a checklist editor with a "restore code tools" button. Actions `UpdateConcreteServerToolsAction` and `ClearConcreteServerToolsAction` (Data `UpdateConcreteServerToolsData`, `ClearConcreteServerToolsData`; events `ConcreteServerTools{Updating,Updated,Clearing,Cleared}ActionEvent`). Clients are served exactly the stored list, in the stored order; `[]` serves no tools. Servers need `Support\Server` or the `HasCortexOverrides` trait (`HasVersionedInstructions` is the same trait under its old name). The `cortex` server cannot be overridden. Stale, failing and ambiguous entries are skipped or resolved to the code tool, logged, and reported in the new `missing_tools` / `ambiguous_tools` fields beside `tools` and `tools_overridden` on the server list and the instructions show. See the README, "Overriding a Concrete Server's Tools".
- New `cortex.mcp.warning_ttl` config key (default 3600 seconds): how long Cortex stays quiet about a server override it cannot serve as saved once it has logged it, per server and entry, across requests.
- `McpServerRegistry::defaultTools()` and `supportsToolOverrides()`.
- **Configurable table names**: every table, the `virtual_agent_sub_agents` pivot included, is named under the new `cortex.tables` config key and read by the migrations, models, validation rules and queries through `Support\Tables`. Keys a published config leaves out keep their default. Every model already has a bundled policy in `cortex.policies`; an arch test now keeps it that way.
- **OAuth redirect domains** managed at runtime instead of only through `mcp.redirect_domains` (`MCP_REDIRECT_DOMAINS`). Cortex keeps a `cortex_redirect_domains` table (new migration) and replaces laravel/mcp's dynamic client registration controller with one that also accepts every stored origin. Domains may belong to any model (an organization, a user) or to no one, and are managed from the new **Redirect domains** dashboard screen (the compiled list of config, global, organization and user domains, filterable by source, where global domains are added), the `/cortex/redirect-domains` API and the `list-redirect-domains-tool`, `create-redirect-domain-tool` and `delete-redirect-domain-tool` MCP tools. Hosts and redirect URLs are stored as their origin; only config can allow `*`. Switch it off with `cortex.redirect_domains.enabled`. `RedirectDomainModel` gets a policy in `cortex.policies` that allows everything, like the other bundled policies.
- The package's section in Atrium's sidebar rail has its own icon (`cpu-chip`) and a fixed place in the rail.
Expand Down
Loading
Loading