Connector tools

These are the tools an agent sees when it connects to Empress. Each acts as the person who connected it, inside their workspace and within their role. Anything a site can do that has no tool of its own is reached through site_call, and work that takes time through work_request.

Orient

whoami

Reads; changes nothing.

Call this first. Returns who this connection acts as (name and email), the workspace, your role in it (Owner, Admin, Operator or Viewer), what an agent acting for you may do on its own (which changes ask first, any budget cap, and what only a person may do), every site you can reach (slug, title, address, status, timezone, and your role on it, which differs from the workspace role only where you hold a role for that site), the plan and how much of each allotment is used, this workspace’s recent usage, and short instructions for using these tools. Pass sites: "archived" to list the sites that are archived (a holding page on their address, their content kept) or were taken down, instead. Call it again whenever a tool refuses for access or a limit, to see which workspace and limits apply.

Argument	Type	Required	What it is
sites	active, archived		Which sites to list.

search

Reads; changes nothing.

Find any tool you can use here, including the many not listed: Empress’s own and every tool of a site’s CMS (EmDash), plus the tools a site’s plugins add when you name the site. Give a few words of what you want to do (“publish a page”, “menu”, “promote”) and get the best matches, each with what it does, whether it reads or changes something, the least role that may call it, and how to call it. CMS and plugin tools are called through site_call: one call with site, tool and args, or sites and calls to run the same calls on several sites at once; platform work (a capability run) is asked for through work_request. Give an exact tool name instead to describe it: its full description and the arguments it takes (its input schema). Read-only.

Argument	Type	Required	What it is
query	string	yes	What you want to do, in a few words, or one tool’s exact name.
site	string		A site’s slug: adds the tools its plugins offer, and is where an exact CMS tool’s arguments are read from.
limit	integer
response_format	concise, detailed

Read

site_status

Reads; changes nothing.

The state of one site (site): what is staged on it compared with what is live — the staged theme release against the live one, how many releases apart, and whether live has moved since the stage was made (a promote then needs force). When something is staged, returns a private preview link to it. Also the open change set, if any (its preview link, content drafts and held menu and settings changes), the latest entries of what went live, each saying whether version_revert can undo it, and its traffic over the last days (default 7, at most 90): views, visitors, engaged time, posts published and top content; the theme in short, with the address of its full brief (a resource to read before changing the theme); and its health: the last check’s verdict in a sentence, the engine it is held on when an engine roll failed on it (with the build phase it failed at, and the way out), its errors over the last day, its newest deployment and its platform layer (where the Worker answers from, where its data lives, whether pages are edge-cached, each with what it costs; read now with site_call “empress.site_platform”) (logs, traces and the rest are site_call operations; search “site logs”). Leave out site for every site at once: each site’s traffic, the workspace totals and the top content across all of them. Traffic comes from daily rollups, so it answers even while a site is down; response_format: "detailed" adds the per-day series. Pass section for one part in full: “history” (what went live, was staged or was previewed, limit entries), “changeset” (the open change set, or the one changeset names, with its preview links, drafts and held changes) “traffic” with a traffic view: a site’s totals and trends over any range, its leading items, one item’s numbers, or who is on it right now, or “builds”: the builds of the site’s theme, newest first, how each ended and where a failure stopped (a build’s log is site_call “empress.build_log”; a running build is followed with work_status). Read-only.

Argument	Type	Required	What it is
site	string		The site’s slug (as whoami lists it); its id also works. Leave it out for the whole workspace.
days	integer		Traffic window in site-local days, ending today.
response_format	concise, detailed
section	history, changeset, traffic, builds		One part in full instead of the short form of every part: “history” (what went live, was staged or was previewed, newest first, each row opening with which and saying whether version_revert can undo it), “changeset” (the open change set, or the one changeset names: its preview links, content drafts and held changes), “traffic” (the numbers; traffic picks the view), “builds” (the builds of the site’s theme, newest first: each one’s outcome, the phase a failure stopped at and its sentence, and which build the site serves; limit entries, kept 90 days).
limit	integer		With section “history” or “builds”: how many entries.
changeset	string		With section “changeset”: a change set by id, open or closed (default: the open one).
before	string		With section “builds”: the next page, as the previous answer’s next gives it.
traffic	object		With section “traffic”: { view: “site”, from, to, groupBy } for totals and trends (groupBy none, day, month, section or author; at most 400 days); { view: “top”, from, to, by } for the leading items (by views, visitors or engaged time); { view: “item”, contentRef, from, to } for one item (its slug or path); { view: “now”, window } for who is on the site right now (1h, 6h or 24h). Days are YYYY-MM-DD, site-local. Without it, the last days in short.

content_query

Reads; changes nothing.

Read content from one site (site, its slug) or from every site at once (sites: "all"). Name a collection to list it, filtered by where (field to value, or to {contains}, {in}, {ne}, {exists}) and sorted by orderBy (createdAt, updatedAt, publishedAt, slug or status) and order. Or pass a query: every word must appear in some field of the item, including private single-page collections (a home page) that full-text search cannot see. With neither, you get the site’s collections. Every item carries liveRevisionId (what visitors see) and draftRevisionId (an unpublished draft, if any). Fields are short by default (long values say how to read them); fields: "all" returns every field whole, fields: ["name", …] just those. Pages hold limit items (default 10, at most 100, or 25 with every field); pass back nextCursor as cursor for more. With all sites, sites that could not answer are listed under unavailable with why: tell the person which sites were skipped. Read-only.

Argument	Type	Required	What it is
site	string		One site’s slug (as whoami lists it). Pass this or sites.
sites	all		Every site in the workspace at once. Pass this or site.
collection	string		The collection to list, e.g. “pages”, “posts” or “home”.
query	string		Words to find in any field of an item. Without a collection, every collection is looked in.
where	object		Field → value it must equal, or an operator object: {“contains”: “text”}, {“in”: [..]}, {“ne”: value}, {“exists”: true}. Fields are the collection’s own, or id, slug, status, locale, createdAt, updatedAt, publishedAt.
orderBy	string		createdAt (the default), updatedAt, publishedAt, slug or status.
order	asc, desc
fields	all or list of string		“all” for every field whole, or a list of field names.
limit	integer
cursor	string		The nextCursor from the previous page of this same query.

site_preview

Changes things.

Look at one of the site’s own pages the way a visitor’s browser draws it, to check a change before calling it done. Renders path (default “/”) of target: “live” (default), “stage” (what theme_stage staged, through its private preview) or “draft” (one item’s unpublished draft: the page a “/<collection>/<slug>” path names, or item), at up to three widths (default 375, 768 and 1280: phone, tablet, laptop). Returns one picture per width, smallest first, each scaled so its long edge is at most maxDimension pixels, with the page’s HTTP status (an error page gets no picture), its size, and a link to the full-size file that works for a few minutes without signing in. Each picture is the first screen unless fullPage: true (the whole page, cut at 6,000 px tall, saying where when the page is taller) or selector (just that element, cropped to its box at each width: the thing being refined, not the page scaled down); the inline picture of a long page is scaled down, so read it at full size by its link. css injects a stylesheet after the page’s own, inside the renderer only — the live page is untouched; with compare: "plain" it draws the page without the css beside the page with it, the changed regions boxed. probes.styles reads computed CSS values for selectors and says plainly when a selector matches nothing; probes.layoutShift measures how much the page jumps while loading (cumulative layout shift; anything above a tenth needs work) and names the elements that moved; probes.measure evaluates one expression in the page after load and returns its JSON result — network requests and navigation are blocked while the expression runs (an expression that triggers a fetch or a navigation gets an error, not a result). compare draws the same page beside it — “live” for a stage or draft, “reference” for the one other origin the site declares (empress.site_reference_set: its production address during a migration; target: "reference" draws it alone), “plain” with css (the page without the css beside the page with it), or {“asset”} for a design frame brought in with media_ingest — both whole, and answers each width’s changed regions as boxes naming the element each sits in, with a link to the picture with the boxes drawn; ad slots present on both sides are masked and counted, and a slot on one side only is a change. probes.tokens finds elements whose border radius, font size, line height, padding or gap, or colour is on no step of the theme’s own token scale; probes.layout finds horizontal overflow, text its box clips, images drawn at another aspect ratio than their own, lines over about 80 characters and text under WCAG AA contrast; probes.type detects font-loading faults — every declared @font-face (loaded, failed, never requested), every distinct text style’s declared vs actually painted family, and findings: fallback painting, face failures, unused faces and uppercase runs. All three are measured at every width and answered once per cause, not once per element: each finding carries count (how many elements share it), entries (the first three selectors it applies to) and the widths it was seen at, at most 200 findings each with the rest counted; detail: true lists every entry. A repeat for the same page, width and release answers from the cache; refresh: true renders again. With url alone, captures that one address on the site’s own domain. list: true lists the captures already taken instead.

Argument	Type	Required	What it is
site	string	yes	The site’s slug (as whoami lists it); its id also works.
target	live, stage, draft, session, reference		Which version of the site to render; “reference” is the one other origin the site declares (empress.site_reference_set), such as its production address during a migration.
session	string		With target “session”: the edit session’s branch (theme_session_start returned it, agent/<name>).
path	string		The page, as a path on the site: “/”, “/about”, “/menu?day=friday”.
item	object		With target “draft”: the item whose draft to draw ({collection, id}), when the path is not /<collection>/<slug> (a home page served at “/”).
widths	list of integer		Viewport widths in CSS pixels, at most three.
probes	object		What to measure while the page is open.
css	string		A stylesheet injected after the page’s own, inside the renderer only — the live page is untouched. With compare “plain”, the page without this css is drawn beside the page with it, the changes boxed. The answer repeats the css so it can become the patch.
compare	live, reference, plain or object		Draw the same page beside this, at the same widths, and box what changed: “live” (with target “stage” or “draft”), “reference” (the site’s declared reference origin), “plain” with css (the page without the css beside the page with it), or {“asset”: “<media id>”} — a design frame brought in with media_ingest, a PNG exported at 1x, compared at its own width. Both sides are drawn whole; each width answers the changed regions with the element each sits in, and a link to the picture with the boxes drawn. Ad slots present on both sides are masked and counted; a slot on one side only is a change.
detail	boolean		The token and layout probes answer each cause once, with its count and the first three elements; true lists every element.
fullPage	boolean		The whole page at each width, not just the first screen; cut at 6000 px tall, and the answer says where when it was.
selector	string		A CSS selector (“section.rail”, “.card-grid”): the picture is that element alone, cropped to its box at each width. Not with fullPage.
refresh	boolean		Render again instead of answering from the cache.
url	string		One full address on the site’s own domain, for a single capture.
list	boolean		List the captures already taken instead of rendering.
variant	card_public, card_authed, capability_before, capability_after, landing_full
maxDimension	integer		Long-edge cap, in pixels, on each picture returned inline. The links are always full size.
limit	integer		With list: how many earlier captures to list.
options	object		For a single url capture: fullPage, viewport { width, height }, waitFor. With widths, only waitFor applies (use the top-level fullPage).

Act on a site

site_call

Changes things, and can remove them.

Run a site’s own CMS tools (EmDash) by name: list and read content, save drafts, publish, manage media, menus, settings and the tools its plugins add. One call: site, tool (the CMS tool’s name) and args. Empress’s own site operations run the same way, by their empress. names — a page’s blocks (empress.composition_get, empress.composition_apply into a draft with a picture of it, empress.composition_publish), lock, archive, clone. Several sites at once: sites (slugs, or “all”) and calls (a list of {tool, args} run in order on each site); the answer gives each site’s outcome in a sentence, lists sites that could not be reached, and says in one line where it worked. Use search to find a tool and its arguments. Reads and drafts run directly; anything that cannot be undone (a delete, a purge) needs confirm: true. Lists need an explicit limit (at most 100). content_update saves a draft: pass the item’s _rev from a read, or leave it out and the current revision is read for you (the answer has the new _rev, the editor link and a preview of the draft); a publish needs the _rev from a read, so a concurrent edit is never overwritten. Pass changeset to hold menu and settings changes in a change set until it is promoted (for a batch, a map of site slug to that site’s change set).

Argument	Type	Required	What it is
site	string		The site’s slug (as whoami lists it); its id also works. One call only.
tool	string		The CMS tool’s name, e.g. “content_list” or “content_update”.
args	object		The tool’s arguments.
confirm	boolean		Required, and must be true, for a tool that cannot be undone.
changeset	string or object		A change set from changeset_create (for a batch, an object of site slug → change set). Menu and settings changes are then held in the set and applied when it is promoted; content edits stay drafts in the set; anything else that would go live at once is refused.
sites	all or list of string		A batch: the sites’ slugs, or “all” for every site in the workspace.
calls	list of object		A batch: the calls to run on each site, in order. A requestKey on a call makes a retried batch record nothing twice.

Ship theme code

theme_stage

Changes things.

Stage a theme release on a site so it can be previewed before anyone sees it. Pass ref (“latest” for the newest release of the theme the site follows, a commit prefix from that theme’s history, or a full artifact hash) or session, an edit session (or any branch of the theme’s repository, such as one pushed from the CLI): its newest commit is built into a release and staged, in one call. Only the stage changes; live traffic is untouched. Returns a private preview link and the release staged; check it with site_preview (target “stage”) before theme_promote. If the stage or the branch build is still running, call again shortly.

Argument	Type	Required	What it is
site	string	yes	The site’s slug (as whoami lists it); its id also works.
ref	string		“latest”, a commit prefix, or a full artifact hash. Or pass session.
session	string		The edit session, as theme_session_start answered it (for example “agent/hero-copy”); the part after “agent/” also works. Any branch of the theme’s repository stages the same way, such as one pushed from the CLI. Or pass ref.
changeset	string		A change set from changeset_create: the stage becomes its theme change and goes live when the set is promoted.

theme_promote

Changes things, and can remove them.

Put the site’s staged release on live traffic, and report what the site now serves. Requires confirm: true. Check site_status first: if live has moved since the stage was made, this refuses unless force: true. For a site that follows its theme through a group, pass choice: "pin" to promote this site only (it stops following group updates until unpinned) or choice: "group" with confirmGroupPublish: true to publish to every site in the group; without a choice it refuses and names both.

Argument	Type	Required	What it is
site	string	yes	The site’s slug (as whoami lists it); its id also works.
confirm	boolean	yes	Must be true: this changes what visitors see.
force	boolean		Promote even though live has moved since the stage was made.
choice	pin, group		Required for a site that follows its theme through a group.
confirmGroupPublish	boolean		Required with choice: "group": it publishes to every site in the group.

Group changes and put them live

changeset_create

Changes things.

Open a change set on a site: one envelope for a request that crosses content, the theme, menus and settings. Pass its id as changeset to site_call and theme_stage: content edits stay drafts, a theme stage becomes the set’s, and menu and settings changes are held instead of going live. Nothing reaches visitors until changeset_promote. A site has at most one open set; asking again returns it. title is the request in the customer’s words. sites (slugs, or “all”) instead of site opens one set per site and returns them by slug, ready for a site_call batch.

Argument	Type	Required	What it is
site	string		The site’s slug (as whoami lists it); its id also works.
sites	list of string or all		Several sites at once instead of site: slugs, or “all”.
title	string	yes	What the change is for, in the customer’s words.

changeset_promote

Changes things, and can remove them.

Put a change set live, in order: publish its content drafts, then its pages’ drafted blocks, promote its theme stage, then apply its held menu and settings changes. Returns what the site now serves, member by member. Requires confirm: true. If a member cannot go live (an item edited since it joined the set, a stage that moved), it stops there, says which and what to do, and nothing after it is applied; calling again carries on. force, choice and confirmGroupPublish pass to the theme stage’s promote exactly as theme_promote takes them. changesets (site → set, as changeset_create with sites returned them) instead of changeset: N sites go live in one call, each set on its own; one that stops never stops the others, and a set waiting on an Admin is named as pending. choice and confirmGroupPublish are refused with changesets: promote that site’s set alone.

Argument	Type	Required	What it is
changeset	string		The change set, as changeset_create or site_status returned it.
changesets	object		Several sets at once instead of changeset: site → set, exactly as changeset_create with sites returned them.
confirm	boolean	yes	Must be true: this changes what visitors see.
force	boolean		Promote the stage even though live has moved since it was made.
choice	pin, group		For a site that follows its theme through a group, as theme_promote takes it.
confirmGroupPublish	boolean		Required with choice: "group", as theme_promote takes it.

Undo

version_revert

Changes things, and can remove them.

Undo one thing that went live on a site, and report what it serves now. to names the entry from site_status’s versions section: a change set (its menu and settings changes go back to what they were, newest first, its theme change is undone, and each page whose blocks it published serves the blocks it had before) or the latest theme promote. Content a change set published stays published and is listed, to unpublish if wanted. Requires confirm: true. Entries that cannot be undone this way say what to do instead.

Argument	Type	Required	What it is
site	string	yes	The site’s slug (as whoami lists it); its id also works.
to	string	yes	The entry to undo, as site_status’s versions section names it.
confirm	boolean	yes	Must be true: this changes what visitors see.

Move files

media_ingest

Changes things.

Put files from another app (a design tool’s export, a drive’s download link, another site’s file) onto one or many sites, without the file ever passing through the conversation. Each item names its target (a site slug, a list of slugs, or “all”) and a sourceUrl: an https download link the site fetches itself (the file must state its size and be at most 50 MB: images, video, audio or PDF). Leave out sourceUrl to get one single-use upload link per site instead, and PUT the file you hold to each (ten minutes). optimize re-encodes an image for its use: “hero”, “card” or “logo”. bind ({collection, id, field}) puts the file into an image or file field as a draft; pass changeset (an id, or a map of site slug to that site’s change set) so one promote publishes every bind. provenance ({app, ref}) records where it came from. A requestKey per item makes a retried call land nothing twice. One call moves a few dozen file-and-site pairs at most; a larger move is refused with how to split it. The answer says, per item, where it landed, its size and dimensions, the media id, and which sites could not be reached.

Argument	Type	Required	What it is
items	list of object	yes
site	string		One site for every item (instead of each item’s target).
changeset	string or object		A change set for the binds (an id, or an object of site slug → that site’s change set).

Extend a site

plugin_install

Changes things.

Install a sandboxed plugin from the plugin registry on one site, by its publisher (the DID the registry lists) and slug, optionally a version. Needs the Admin role and confirm: true: a plugin runs code on the site. Plugins built into the site (an npm package) are part of the engine every site runs on, so they cannot be installed here; the answer says so. Use search for “plugin” to list a site’s plugins first.

Argument	Type	Required	What it is
site	string	yes	The site’s slug.
publisher	string		The plugin publisher’s DID, as the registry lists it.
slug	string		The plugin’s slug in the registry.
version	string		A version (default: the latest).
package	string		An npm package name (a built-in plugin: refused, with why).
confirm	boolean		Must be true: the person you act for agrees.

Platform work

work_request

Changes things, and can remove them.

Ask the platform for work that is not instant or happens platform-side, by operation name: operation, the sites it lands on (slugs), and the operation’s args. Today: empress.capability_run (args: { capability, args }), such as moving a site onto the current engine with capability: "engine_roll"; empress.program_run (args: { program, inputs?, title?, changeset? }), a short program over the Empress model (read skill://empress-model.md) whose every call is the call you could make by hand, on as many sites as it names; and empress.work_order (sites: the one site, args: { intent, mode }), Empress triaging or investigating a problem on a site behind the scenes, then args: { order, action } to accept, revise (with feedback), take over or decline what it found. Use search to find an operation and its arguments. The answer is a task (taskId, state); follow it with work_status until it is done. Work that can replace what a site serves needs an Admin’s yes: confirm: true from an Admin, else it waits for one in the console.

Argument	Type	Required	What it is
operation	string	yes	The platform operation’s name, e.g. “empress.capability_run”.
sites	list of string		The sites the work lands on, by slug (as whoami lists them).
args	object		The operation’s arguments.
confirm	boolean		True once the person you act for agreed, for work that needs a yes.

work_status

Reads; changes nothing.

Where a task from work_request stands: state is queued, running, needs_input (it waits for a person), done or failed, with each site’s outcome. Call again while it is queued or running. A work order answers its order: where it stands in words, the evidence it found, the staged fix to look at, the actions it takes, and its receipt (one metered line per stage). A theme build’s id (from theme_stage, empress.theme_check or site_status section “builds”) is a task too: it answers the build’s phase (“phase 3 of 7, installing dependencies, 12 s in”), how it ended, and the last lines of its log. So is a promote’s run id (theme_promote’s runId) while its pages are checked: it answers whether they passed, or what was put back and why. A stage’s runId (theme_stage) and a session Preview’s runId (theme_check’s preview) are tasks too: they answer the deploy’s state and phase; while one runs, follow it, never build again.

Argument	Type	Required	What it is
taskId	string		The task’s id from work_request. Leave it out to list the workspace’s work orders, newest first, at most 50: the site, mode, state, who or what opened each (a person, a Workers Issues alert, or the render gate) and the id to pass back here.
state	open, closed, all		With no taskId: which work orders to list. Default open.
site	string		With no taskId: only the work orders on this site, by slug. Ignored when taskId is given.

Tell Empress

empress_feedback

Reads; changes nothing.

Tell Empress what got in the way: a tool that refused something it should allow, an answer that was wrong or confusing, something missing, something slow (or something that worked well). Write it in plain words for the people who build Empress, as the person you act for would say it, with what you were trying to do. It is recorded against this workspace and read by the team; it changes nothing on any site. It is the human-written sibling of the engine request a tool records itself when it refuses a change to the platform’s engine: after such a refusal, say here what the person needed in their own words; use it for everything else too.

Argument	Type	Required	What it is
category	bug, missing, confusing, slow, praise, other	yes	bug (it did the wrong thing), missing (it cannot do it), confusing (the answer or the refusal was unclear), slow, praise, other.
severity	blocking, annoying, minor	yes	blocking (the task could not be finished), annoying (it took a detour), minor.
verb	string		The tool or skill it is about, by name. Leave out for the whole connector.
message	string	yes	What happened and what you were trying to do, in plain words.
site	string		The site it happened on (its slug), if any.