Skip to content

Layout writes an agent can and can’t reach

The `html` module shows in the catalog like any other, but a layout write introducing one is rejected below `siteAdmin`, even off the admin editor.

Kywi withholds exactly one module type from anyone below siteAdmin: html. An agent authenticated with a lower-scoped key sees it in list_module_types like any other built-in, but a layout write that introduces or edits an html module is rejected — the same rule the admin editor's palette enforces by hiding the module from the drag list in the first place, mirrored server-side so the palette isn't the only thing standing in the way.

What the rejection looks like

Every door a layout write comes through runs through one guard before anything is stored. A rejected write comes back as a 403 with a structured reason, not a stack trace:

the 403 body the layout write returnsjson
{
  "error": {
    "code": "FORBIDDEN_MODULE",
    "message": "Your role may not add these module types: html"
  }
}

That is what the route returns. What the agent sees is that body flattened into the SDK's error message — Kywi SDK error (403): {…}, the JSON carried as a string on an exception rather than a structure the tool loop can branch on. An agent handling the refusal reads the message text; there is no parsed code field waiting for it.

The check diffs the incoming document against what's already stored, by module id: an agent may re-save a page that already carries an admin-placed html block untouched, and may move it around, but adding a new one or editing an existing one's props is what trips the guard — existence alone isn't the trigger, content is.

The gate follows linked components too

Placing a module isn't the only way to introduce one. Linking a layout node to a component definition that itself contains an html block puts the same markup on the page, so the guard checks that path as well: a newly added component link is expanded to its stored definition, and an html block inside it counts as introduced. An agent can't sidestep the gate by stashing the block in a component and linking to it instead.

The module tools reach the main layout only

update_module_props, remove_module, add_module and remove_row find their target by region, row and column among the sections placed directly in the page's main layout. A section inside a personalized or A/B tested container, a module that is one arm of a personalized module, and anything in a page variant are not there, so those tools return an error. For those nodes the agent reads the page with get_layout, changes the node in place, and writes the whole document back with update_layout.

Custom module types are the developer server’s list, not this one

list_module_types maps the engine's own built-in palette and nothing else. A module declared in kywi.config.ts with defineModule is not in it and never will be — the site MCP server talks to a running site over REST and never reads that file. Custom types are listed by get_modules on the developer server in api mode, which reads the config through the running site instead of the file. In filesystem mode that same tool comes back empty — its config parser looks for a quoted name as defineModule's first argument, but a module is declared as defineModule({ name: ..., ... }), a single object, so nothing ever matches. Either read kywi.config.ts yourself in that mode, or tell the agent the type names directly; an agent holding only the site server's tools cannot enumerate a project's custom modules at all, and update_layout will place them once it's told.