agenta-ai / agenta-apps

Agenta apps

When

The person asks for something to look at and touch rather than a reply: a board, a checklist,
a queue, a form, a table, a small dashboard. Build an app folder in the drive; the drive renders
it in a sandboxed page and shows it as a card in the chat. Do not build one for a one-off answer.

First

1. List apps/*/app.json. If an app already covers the ask, update its files; never make a
   second copy of the same app.

2. Pick a starter from the table below and call create_app(starter, "apps/<slug>"). Then write
   its config file and, when the person gave you content, its data file.

3. Only when no starter fits, write app.json and index.html yourself (rules below).

Folder

apps/<slug>/ holds app.json (the manifest: agenta_app: 1, name, entry, access,
data, config), index.html, and its data as sibling JSON files. Set access to
read-write if the app saves anything, else read. The app owns what data names while it
is open; you own config and the rest. You may write data too, but read it first: your writes
are unconditional.

Bridge

The page gets window.agenta: await agenta.ready first; then canWrite, visible, dir,
and agenta.fs with read, readJSON, write, writeJSON, list, exists, stat,
remove. Paths are relative to index.html and cannot leave the folder. Events:
agenta.addEventListener("changed", cb) when a file changes underneath the app, "access"
when canWrite changes, and "visibilitychange". Failures reject with error.code:
not_found, read_only, scope, conflict, too_large, bad_request, unavailable.
Writes carry If-Match automatically.

Custom app rules

• Layout with the kit classes only: ag-app, ag-toolbar, ag-btn, ag-btn-primary,
  ag-input, ag-select, ag-check, ag-card, ag-columns, ag-column, ag-list,
  ag-grid, ag-badge, ag-empty, ag-toast. Inline CSS only for what they do not cover.

• Keep assets self-contained. Do not assume network isolation or embed secrets.

• Wait for agenta.ready; treat not_found as empty; while canWrite is false, show edits
  as unsaved instead of failing; on access, re-render and save them.

• Save whole files, debounced, after each change; handle conflict by re-read and reapply once.

Starters

create_app copies the starter; list_starters shows this table live.

After

Reply with the file card for apps/<slug>/index.html and say which access the app asks for
(read or read-write).

Agent-level layout: agent-files/.apps/

agent-files/.apps/ is your record of the apps you have built, across sessions.
Do these in order; each rule is a checklist item.

1. First create_app in this agent's life: write agent-files/.apps/layout.json as
   {"version": 1, "created_at": "<ISO 8601>"}. If the file already exists with a different
   version, stop and say so. Do not guess at a migration.

2. After every app event in this session (create, update, archive): rewrite
   agent-files/.apps/registry/<session_id>.json whole, as
   {"version": 1, "session_id": "<id>", "apps": []}, one object per app, string keys
   slug, path, template, created_at, updated_at, state, notes. Never write
   another session's registry.

3. Before creating an app: read every file under agent-files/.apps/registry/ and merge by
   slug. If the person is asking for something you already built in this session, update it.
   If you built it in another session, say so and offer to recreate it here from the same
   starter. When two sessions hold the same slug, keep the one with the later updated_at;
   if those are equal, keep this session's. Never merge two records into one, and never
   rewrite the other session's file to resolve it: the merge is what you read, not what you
   write.

4. Repeated feedback: when the same feedback arrives about the same starter twice across
   sessions, add agent-files/.apps/notes/<YYYY-MM-DD>-<slug>.md with one paragraph and the
   session ids. Never edit or delete an existing note.

5. Scheduled data: if an app's data is produced on a schedule (a dashboard, a weekly
   sweep), propose a schedule in Triggers when you have create_schedule. Say plainly that a
   scheduled run writes into its own session, not this one, so the app will not refresh itself
   here: the person reopens it after a run, or asks you to copy the new data across. Apps live
   in the session drive; create_app cannot write to agent-files/, so do not offer to put one
   there.

6. Never put app data files under .apps/. Never touch .apps/kit/ unless the person
   asks for branding.