arizuko › concepts › web-native agents

web-native agents

An arizuko folder can serve a public website. The site has pages that the agent writes into ~/public_html/, an embedded chat widget and a form intake. A folder needs the web:publish grant for the site to exist.

One folder serves pages, a chat widget and a form

The three web parts share one guest per turn and one history:

part	what it does	path
public page	The agent writes HTML, PNG or JSON into `~/public_html/`, a bind mount of the folder web directory, and `vited` serves it to anyone on the next request.	`/pub/<folder>/*`
chat widget	`slink` embeds in the page, and messages land at `web:<folder>`.	`/chat/<token>/`
form intake	Each POST lands at `web:<folder>/<sub>`. That JID needs a real child group, for example one made with `register_group` for `atlas/strengths/submissions`, because each web JID maps to exactly one group.	`/chat/<token>/` with a suffixed JID

A private counterpart, ~/private_html/, is served at /priv/<folder>/ behind OAuth, for content that is not public.

The /pub/<folder>/ path always works. A world can also get a short host name. When HOSTING_DOMAIN is set, proxyd answers <folder>.<HOSTING_DOMAIN> with a 302 redirect to /pub/<folder>/, with no configuration per host and no map file. An agent finds its own public URL with the get_web_presence tool.

A visitor request reaches the agent and comes back as a file

visitor
  GET /pub/<folder>/  ──►  vited  ──►  static HTML + chat widget

  POST /chat/<token>/  ──►  webd  ──►  message at web:<folder>
                                          │
  POST /chat/<form-token>/ ──► webd ──► message at web:<folder>/submissions
                                          │
                                          ▼
                                        routd
                                          │
                                          ▼
                                    guest (agent)
                                          │
        agent writes  ──►  ~/public_html/<name>.html
                                          │
                                          ▼
                          next GET /pub/<folder>/<name>.html
                          serves the file the agent just wrote

The form token has the suffix submissions, so its JID is web:<folder>/submissions. That JID names a child group, which keeps form posts apart from the page chat.

A form post becomes a personal report

This example assumes a skill that you write, named process-strengths here. No such skill ships in ant/skills/. A visitor opens /pub/atlas/strengths/ and sees an intake form. The visitor pastes Gallup CliftonStrengths results and clicks submit.

The form posts to /chat/<form-token>/, and webd writes a message into web:atlas/strengths/submissions. The group atlas/strengths/submissions must exist, because each web JID maps to exactly one group folder and the route table does not apply.
routd starts the turn, and runed starts the atlas/strengths/submissions guest to process the form post.
The agent runs the process-strengths skill and writes ~/public_html/strengths/<name>.html. The file is served at /pub/atlas/strengths/submissions/strengths/<name>.html.
The agent replies with that path, and vited serves the personal report on the next request.

The site has three limits

One folder is one site. Sub-sites under one folder share the same agent, ACL and history. For separate sites, use separate folders.
A page is what the agent writes. No template layer reads from a database, so a dynamic page needs a skill that writes the HTML.
vited is the origin, with no CDN and no edge cache. Put one in front if the traffic needs it.

Six pages cover the parts

routing: how web:<folder> and web:<folder>/submissions reach the correct agent.
route tokens: the /chat/<token>/ URL that the page and the form post to.
tasks: schedule the agent to rebuild or clean the site.
skills: the markdown instructions that turn a form post into HTML.
webdav: the file workspace that the agent writes through.
how-to: chat link: create the token that the page embeds.