Extensions

Two ways to extend

Extensions come in two tiers. Addons are cherry π's own parts, shipped inside cherrypi.ape. Apps are .pi files anyone can write.

The core is never a plugin: authority and policy, receipts, confinement, the addon loader and the verb registry stay in cherry π itself.

Addons

An addon is a first-party part of cherry π that plugs into a registry the core owns. Addons are found only inside the APE, so nobody can drop one in. Code of your own goes in a .pi app.

List and turn on addons

picache addons                      # every addon in this build
picache addons enable cellardoor    # grant what it needs and start it
picache addons disable cellardoor   # stop it

Each line of the list shows the addon's id, its state, its version and what it needs.

Enabling an addon grants every capability it declares. Only you can enable or disable one, and anyone else is told operator_decides.

Your choice is kept as the setting addon.<id>.enabled, so it holds across restarts.

Two buttons do the same for you: Turn P2P on in Machines, and Open a world on this layer in Actions, which needs Cellar Door enabled.

The addons in this build

p2p_holepunch conflicts with p2p_libp2p and p2p_iroh, so only one P2P backend can run.

What an addon's state means

Addons start in dependency order. Two addons that conflict are refused, and so is a missing dependency or a cycle.

A failure never stops the harness. It is recorded in three places:

• a line in <state root>/logs/addons.log
• a receipt, addon.activation_failed
• an event of the same name to the desktop.

Where addons plug in

An addon can register only in these places. Anything else is refused with registry_unknown. When an addon stops, everything it registered goes with it.

An addon can declare only these capabilities: sidecar.run, network.peers, p2p.peers.read, p2p.presence.read, p2p.session.open, p2p.session.send and p2p.bond.manage. None of them can be granted to an app.

.pi apps

A .pi app is one SQLite file that holds the whole app: its manifest and signature, its Lua handlers, its assets and its own data. The field manual shows what is signed and what isn't.

Install an app

picache app install notes.pi          # a packed app
picache app install ./notes           # a folder you're writing, run in place
picache app grant notes appdata:own   # grant one capability, for this session
picache app grant notes appdata:own --always
picache <id> <verb>                # an app's verb, such as picache notes add

Whether you're asked depends on who signed it.

A packed app is copied to <state root>/apps/<id>.pi. A folder runs where it is and is marked unsigned wherever it shows.

Grants are tied to the app's exact content. If the file changes, none of it runs until you review it and run picache app accept <id>. For a folder you're editing, set apps.dev_changes to follow to keep its grants. Each edit is still receipted.

Use the Extensions pane (Actions → Open Extensions) to do the same with buttons: install, grant, deny, open an app's pane, remove.

App commands

Installing, removing, packing, testing, granting, accepting, changing settings and serving are yours alone. Anyone else is told operator_decides.

Write the manifest

An app folder has manifest.lua, handlers/main.lua, and optionally schema.sql and assets/. The manifest is data, never code: a function or require in it is refused.

return {
  schema = "cherrypi.app.v1",
  id = "notes",                 -- lowercase, up to 64 characters
  name = "Notes",
  version = "0.1.0",
  capabilities = { "app.capability", "tools.custom", "appdata:own" },
  storage = { tables = { { name = "notes", mirror = "none", schema_version = 1 } } },
  settings = { { key = "sort", type = "choice", default = "newest", choices = { "newest", "oldest" } } },
  contributions = {
    verbs = { { name = "add", summary = "add a note" } },
    tools = { { name = "search", summary = "search notes",
                parameters = { type = "object", properties = { q = { type = "string" } } } } },
  },
}

What an app can add

Each contribution has a name (lowercase, at most 48), a summary, and the capability it runs under, which the manifest must also ask for.

handlers/main.lua returns a table with a function for each: verbs.<name>(q), tools.<name>(q), hooks.<name>(q), and for a pane render and action, or start, key, resize and tick for a program.

A layout lists every command its terminals may run, and layout.apply asks you each time. A plain shell or an agent pane is refused, and so is anything over 16 panes.

Hooks

A hook hears a call at one of four points. Its answer is labelled as the app's, and it can never approve, change a call or answer a question cherry π asks you.

A hook has two seconds to answer. An answer that is slow, fails or is unclear counts as no opinion. Its text is cut at 500 bytes. A block refuses the call with hook_blocked, naming the app.

Capabilities

An app holds only what you grant, checked at every call. Each capability it asks for is granted separately.

Some are never an app's at any level: your files (drive.*), the addon capabilities, and the core's own, such as store.write and approval.resolve. A manifest that asks for one is refused.

A grant is for this session or always. A session grant ends when the harness restarts, and you're asked again. Deny takes it back, and a program pane running under it ends at its next call.

Ask cherry π to do something

A handler can't reach cherry π directly. It answers { ask = { verb, args }, cont }, and the harness runs the verb and calls the handler again with the result. One call may ask up to 16 times, and every ask is receipted.

The capsule

Handlers are Lua, and run in a capsule sealed to the one capability the call is under. On a machine that can't confine, apps don't run (app_unconfinable).

• They get Lua's string, table, math and utf8 libraries, plus JSON, and have no file, process or network access.
• require reaches only the app's own handler files.
• An answer has 10 seconds and at most 256 KiB.
• Work longer than one call is a loop that the harness steps and recovers, so no app code is left running. A loop has at most 50 steps.

An app's own data

Tables declared in storage and created by schema.sql are the app's to write. They sit outside the signature, so writing them never breaks it.

• schema.sql may hold only CREATE TABLE and CREATE INDEX.
• Each read or write is one statement. Writes go only to the declared tables.
• Writes are journaled for sync with paired machines, except in a table whose mirror is "none".
• Declaring tables needs appdata:own.

install --replace carries the rows into the new version and runs its migrations. A version that drops a column or changes a table without a migration is refused before anything is written. The old file is kept in <state root>/apps/backups/.

Meta, the first app

Meta inspects and packs .pi files, itself included. Install it with picache app install apps/meta from a checkout. It adds the verbs list, inspect, rows, query, pack and edit, an Inspector pane and a SQL program pane. It asks you each time it signs.

Cellar Door worlds

A world is a place you walk through in a terminal pane: scenes of animated art, doors between them, and spots to chat. Cellar Door runs it, and cherry π gives it a layer, panes and, when the layer is shared live, the other members.

Cellar Door comes in two parts.

What a world is

A world is a folder with a world.json and its scenes. Put it in the layer's folder, either at the top or in world/.

• Scenes are the places, each a file under scenes/.
• A scene holds objects: art, chat spots and doors.
• A door leads to another scene, or to another world by its address.

world.json names no layer, pane or path of cherry π's, so the same world runs in Cellar Door on its own.

No world ships with cherry π. AFTERHOURS, from the Cellar Door repository, is the one to try: three scenes, 20 animated pieces, three chat spots and doors in a loop.

Open a world

picache addons enable cellardoor   # once

Then, in the layer, choose Actions → Open a world on this layer. Its sidecar starts, and you're told how to walk in.

An app with app.world can open one with the host verb world.open. You're asked every time, and shown the layer and its folder.

A layer has one world at most. It closes when the layer closes, and its sidecar is stopped.

Walk in

cherrypi-world attach          # in a pane on that layer
cherrypi-world attach --wait   # wait up to 15 s (at most 60) for it to start

The pane becomes a console on the world, drawn in text. Ctrl+] leaves it and gives you the pane back.

Who can walk in

Two kinds of pane can attach:

• Your own shell, as you.
• A pane an app's layout opened, as that app, while it holds app.world.

Anything else is refused with world_attach_refused. The console never names a layer or a person. The harness works that out and vouches for it, and each console gets a one-time ticket that lasts 10 seconds. Attaching gives you presence in the world and no right to change it.

Where a world's files go

A sidecar that exits is started again after 1, 2, 4… up to 60 seconds. Closing sends it SIGTERM, then SIGKILL five seconds later if it's still there. The sidecar runs unconfined, as a job does.

A world app's layout

A world app brings its layout: a world pane, a room for chat, files beside it. It declares the layout and every command the layout's terminals may run.

capabilities = { "app.layout" },
contributions = { layouts = {
  { name = "world", asset = "layouts/world.json",
    runs = { { "bin/studio", "-world", "assets/worlds/afterhours",
               "-control", "world.sock" } } },
} }

Apps run Lua only, so a .pi can't carry Cellar Door's program. The layer's folder has to be a Cellar Door checkout with the program built.

Share a world

When a layer is shared live, its world is shared too. Every member runs the whole world on their own machine. There's no world server and no relay.

The harness writes each event with the machine it came from. The world never says who it is. A row that lies about who wrote it is skipped on every member, so every copy stays the same.

Motion goes over the connections the layer already uses. Only the layer's other members can send it. A frame is at most 1 KiB, and anything faster than 20 a second is dropped. Losing a frame is harmless, because each one carries the latest position.

If your harness restarts, the sidecar replays the log from the start and carries on.

A world whose characters move by themselves, such as followers, is not shared, because on two machines they'd drift apart. It runs on each machine alone, and you're told why (world_rules_unshared).

Edits reach the log from Cellar Door's Studio, started with -propose and the sidecar's socket. A console proposes nothing, so chat typed in a console stays on that machine.