@centralu/win32-x64 0.1.0-beta.9

package/Centralu/resources/host/app-template/AGENTS.md

@@ -0,0 +1,87 @@
+# {{APP_NAME}} — a Centralu app
+
+This folder is one app. Centralu runs `server.mjs` as an MCP server; people use it through its
+screen (`ui/index.html`) and agents call the same tools as functions. Same tools, one code path.
+
+## Files
+
+- `centralu.app.json` — the manifest. `id` is `{{APP_ID}}` and must stay equal to this folder's
+  name. `home` is the tool Centralu calls to open the screen.
+- `server.mjs` — the MCP server. Change it.
+- `ui/index.html` — the screen. Change it. It is read on every open, so edits show without a restart.
+- `runtime/` — **generated by Centralu. Never edit, format, move, or read it in full.** It is replaced
+  when Centralu updates. Everything you need is imported from `./runtime/centralu-app-runtime.mjs`:
+  `McpServer`, `serveStdio`, `z` (zod), `centralu`, `inputRequired`, `acceptedContent`.
+
+## Rules
+
+1. **No installs.** No `npm install`, no `package.json`, no imports other than Node built-ins
+   (`node:*`) and the runtime. The app must start with `node server.mjs` alone.
+2. **Tool names** use letters, digits, `_` or `-`. **Never `__`** (two underscores separate names
+   in agent sessions; Centralu drops such tools).
+3. **Register tools with `centralu.tool(server, name, config, handler)`** (same arguments as
+   `server.registerTool`). The handler then knows which call it is serving, which
+   `centralu.agent()` needs.
+4. **Annotate every tool**: `annotations: { readOnlyHint: true }` if it only reads,
+   `readOnlyHint: false` if it changes anything. Read-only tools run without asking the person;
+   the others follow the session's approval setting. The same hint decides refreshes: every call to
+   a tool that is not `readOnlyHint: true` tells this app's open screens to read again (rule 8). A
+   read tool left unannotated costs a refresh cycle each time it is called, and screens that re-read
+   with it keep refreshing each other.
+5. **Visibility**: by default a tool is visible to agents and to the screen. A tool only the screen
+   should call gets `_meta: { ui: { visibility: ['app'] } }`; one only agents should call gets
+   `['model']`.
+6. **A tool with a screen** gets `_meta: { ui: { resourceUri: 'ui://{{APP_ID}}/…' } }`, and the
+   resource is registered with `centralu.uiResource(server, name, uri, new URL('./ui/…', import.meta.url))`.
+   The `home` tool must have one and must be visible to the screen.
+7. **State lives in the server, never in the screen.** Keep it in memory and save it in the data
+   folder with `await centralu.readJson(file, fallback)` / `await centralu.writeJson(file, value)`
+   (or any file under `centralu.dataDir`). **Never write files into this folder** — a project app's
+   folder is committed to git and shared with the team. The screen may not use browser storage
+   (it runs in an isolated frame).
+8. **The screen re-reads, it does not remember.** When anyone calls one of this app's tools that
+   is not `readOnlyHint: true`, Centralu sends open screens `centralu/notifications/changed` (the
+   screen that made the call does not get it: it already has the answer); the template's screen
+   then calls `show` again. Keep that handler, and keep `show` read-only.
+9. **stdout is the MCP channel.** `console.log` is redirected to stderr for you; never write to
+   `process.stdout` yourself. stderr is shown to the person when the app fails.
+10. **Asking the agent**: inside a tool handler, `await centralu.agent('prompt', { schema, tool })`
+    asks the agent of the person using Centralu. Each call runs in a new session under this app
+    (the person can read it), with the `safe` approval setting, and returns the agent's final
+    answer: text, or with `schema` (a JSON Schema whose top level is an object) JSON of that shape,
+    checked by Centralu. Under `safe` the agent reads without asking, but every file write and
+    command waits for the person to approve it in that session, so ask the agent for an answer and
+    do the writing in your own tool code. Declare `"uses": { "agent": true }` in the manifest for the person's
+    default agent, or a list such as `["codex"]` to pick one with `tool`. The prompt reaches the
+    agent marked as written by this app, not by the person, so say plainly what you need. A run
+    takes seconds to minutes; the helper keeps the call alive while it waits. An app runs one agent
+    at a time and at most 5 a minute: put a batch of work into one prompt instead of a loop.
+11. **Calling another app**: inside a tool handler, `await centralu.callApp('other-app', 'tool', args)`
+    calls a tool of another app and returns its answer (JSON if the tool returns structured
+    content, else text). Declare the app in `"uses": { "apps": ["other-app"] }`. Only tools open to
+    agents (visibility `model`) can be called. A project app reaches apps of its own project first,
+    then apps in the person's user folder; an app in the user folder reaches only user-folder apps.
+    A chain of apps calling apps stops at 3 calls deep, and an app tool already in the chain cannot
+    be called again from inside it.
+12. **Reading Centralu's data**: inside a tool handler, `await centralu.host('sessions.list')` or
+    `await centralu.host('git.status')` returns JSON. These two names are the whole list; declare
+    each one you use in `"uses": { "host": [...] }`. `sessions.list` gives this project's sessions
+    (the names shown in the sidebar and their states, never the conversations); `git.status` gives this project's branch and changed
+    files (project apps only).
+
+All three throw an error that says what Centralu answered. The first time the app uses each of them (an
+agent tool, another app, a host name), Centralu asks the person once — on the session's approval card
+when an agent's call started it, on this app's screen when the screen did — and remembers the answer
+until the manifest's `uses` changes. The call waits while the person decides (up to 5 minutes). A
+refusal comes back as that error: show it plainly instead of retrying.
+
+## Checking your work
+
+- Call Centralu's **`check`** tool after changes. It validates the manifest, starts the app, lists
+  its tools for real, reads every screen the tools point to, and reports problems (tool names,
+  visibility, missing annotations, a `home` without a screen) with the app's stderr.
+- Centralu restarts the app once at the end of your turn if this folder changed; calls in progress
+  finish first. Agents in other sessions see changed tools from their next turn (Claude) or next
+  thread (Codex).
+- Errors in `server.mjs` are printed with file and line. A failure inside `runtime/` is almost always
+  a wrong argument from `server.mjs` — look at the first frame outside `runtime/`.

package/Centralu/resources/host/app-template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/Centralu/resources/host/app-template/centralu.app.json

@@ -0,0 +1,9 @@
+{
+  "manifestVersion": 1,
+  "id": "{{APP_ID}}",
+  "name": "{{APP_NAME}}",
+  "version": "0.1.0",
+  "description": "{{APP_DESCRIPTION}}",
+  "server": { "command": "node", "args": ["--enable-source-maps", "server.mjs"] },
+  "home": "show"
+}

package/Centralu/resources/host/app-template/gitattributes

@@ -0,0 +1,2 @@
+# runtime/ is generated by Centralu and replaced when Centralu updates — not reviewed, not diffed.
+runtime/** linguist-generated=true -diff