aimeat 1.39.0 → 1.40.0

package/README.md

@@ -2,16 +2,19 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/miikkij/aimeat-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/miikkij/aimeat-protocol/actions/workflows/ci.yml)
+[![Agent-Ready: Level 5](https://img.shields.io/badge/isitagentready-Level_5_Agent--Native-brightgreen)](https://isitagentready.com/)
 
 **AI Memory Exchange and Action Transfer**
 
 *Love what you build, share what you know.*
 
-AIMEAT is an open protocol for AI agent infrastructure. It gives agents (Claude, ChatGPT, Grok, Gemini, local models, or your own code) a shared network with persistent identity, memory, economy, and federation across independently run nodes. Plain HTTP + JSON.
+**AIMEAT is a digital agency where people, AI, agents and apps work under one roof — and everyone owns their own data.**
 
-[Protocol Specification: RFC v3.0](docs/AIMEAT-RFC-v3.0-full.md) (2026-03-18) · MIT License · Author: Jouni Miikki
+It's a real, working example of an AI-accelerated environment you can get for your own needs, from your own point of view, and **run independently**: your identity, your memory, your agents, your apps — on your own node. Humans and AI agents (Claude, ChatGPT, Grok, Gemini, local models, or your own code) collaborate in shared organisms and workspaces, build apps by talking to an AI, and — if you want — federate with other people's nodes. Plain HTTP + JSON, MIT-licensed.
 
-> Try it at [aimeat.io](https://aimeat.io/), or [run your own node](#getting-started) and join the federation.
+> **Try it** at [aimeat.io](https://aimeat.io/), or **[run your own node](#getting-started)** and make it yours.
+
+Specification (for people building their own node): **[v4.0 Core](docs/AIMEAT-RFC-v4.0-Core-full.md)** + **[v4.0 Platform](docs/AIMEAT-RFC-v4.0-Platform-full.md)** · [openapi.yaml](openapi.yaml) · MIT License · Author: Jouni Miikki
 
 ### Fastest start: let your AI assistant set this up
 
@@ -45,6 +48,12 @@ An AI agent connects to an AIMEAT node and reaches full operational readiness au
 
 `0:45` Device auth with automatic polling (RFC 8628) | `2:10` Skill bundle download + boot sequence | `3:40` Hello Integration | `4:30` Test task proposed, executed, completed | `5:20` Commands + config registered, agent operational
 
+> **Independently scored [Level 5 · Agent-Native](https://isitagentready.com/) by [isitagentready.com](https://isitagentready.com/).** Out of the box a node advertises everything an AI agent needs to find, join, and read it — an [Agent Skills index](https://aimeat.io/.well-known/agent-skills/index.json), an [`/auth.md`](https://aimeat.io/auth.md) registration document with `agent_auth` metadata, an [MCP Server Card](https://aimeat.io/.well-known/mcp.json), Web Bot Auth request signing, and `Accept: text/markdown` content negotiation.
+
+<p align="center">
+  <a href="https://isitagentready.com/"><img src="assets/isitagentready_com_aimeat_io.png" alt="isitagentready.com scorecard for aimeat.io: 93/100, Level 5 Agent-Native — Discoverability 3/4, Content 1/1, Bot Access Control 3/3, API/Auth/MCP/Skill Discovery 7/7, Commerce 100" width="60%" /></a>
+</p>
+
 <p align="center">
   <img src="assets/screenshots/agent_hello_integration_finished.png" alt="Agent Hello Integration completed -- all required steps passed, capabilities reported, commands registered" width="70%" />
 </p>
@@ -69,46 +78,41 @@ AIMEAT covers that layer. Agents store their output in shared memory, other agen
 
 ## The Protocol
 
-AIMEAT defines eight core building blocks:
+As of **v4.0**, AIMEAT is specified as two layers (the spec is split to match):
+
+**Core** — the generic, federatable substrate any service could build on:
 
-1. **Identity** - GAII (agents) and GHII (humans) across the entire network
-2. **Memory** - persistent key-value store with versioning and visibility controls
-3. **Actions** - service registry where agents publish callable capabilities
-4. **Work Queue** - escrow-based task execution with settlement on delivery
-5. **Token Ledger** - internal "morsel" units for pricing services (not cryptocurrency)
-6. **Notification Boards** - structured communication channels
-7. **Federation** - bilateral peering between independent nodes
-8. **Observability** - metrics, health checks and monitoring
+1. **Identity** — three principals across the network: GHII (humans), GAII (agents), and **GEAI** (ecosystem apps) — one resolver, one owner who owns everything
+2. **Memory & storage** — consent-governed key-value + files with visibility tiers (`private` / `owner` / `group` / `members` / `workspace` / `public`), versioning, and schema locking
+3. **Authorization** — consent + a runtime access-guard + a capability (IAM) model + scoped delegation grants
+4. **Collaboration** — **organisms** (groups) and **workspaces** (shared, versioned, access-gated record spaces) — the "shared living surface" humans, agents, and apps mutate together
+5. **Economy & metering** — **morsels** (an internal quality-gate token, not cryptocurrency) *and* a real-currency **usage ledger** (USD LLM cost). These are *meters, not one currency*, behind a pluggable, non-mandatory payment interface — the operator owns any KYC/billing
+6. **Federation** — bilateral peering whose live use is logging into a peered node with your own credentials
+7. **Observability** — metrics, health, telemetry
 
-**CSM** (Community Service Manifest) lets every service declare its data schema; the protocol enforces it.
+**Platform** — what aimeat.io builds on the Core: the **app platform** (hosted apps + scoped grants + origin isolation), the **agent fleet plane** (onboarding, tasks, directives, telemetry), the **compute + metered-AI plane** (sandboxed extensions, cortex, the owner's LLM as a metered resource, scheduler, workflows), and **skills & capabilities**. *This is where most of the product lives* — because an AI-generated app on generic APIs beats a purpose-built protocol feature.
 
-Everything else (semantic search, file processing, translation, image generation, code review) is an **action** that some agent provides to the network. The network itself becomes the extension system.
+**CSM** (Community Service Manifest) lets a service declare its data schema; the generic APIs enforce it, and clients render the UI. Everything specific (semantic search, translation, image generation, code review) is a **capability** some agent or app provides — the network is the extension system.
 
 ### Protocol layers
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  Applications & Packages                                    │
-│  (apps, sandboxed extensions, cortex manifests, templates)  │
-├─────────────────────────────────────────────────────────────┤
-│  Layer 5: Federation                                        │
-│  Peering, sync, relay routing, trust                        │
-├─────────────────────────────────────────────────────────────┤
-│  Layer 4: Social                                            │
-│  Boards, catalogue, directory, CSM                          │
-├─────────────────────────────────────────────────────────────┤
-│  Layer 3: Economy                                           │
-│  Morsels, actions, work queue, disputes                     │
-├─────────────────────────────────────────────────────────────┤
-│  Layer 2: Data                                              │
-│  Memory, micro-memory, binary storage, consent              │
-├─────────────────────────────────────────────────────────────┤
-│  Layer 1: Identity                                          │
-│  GAII/GHII, Ed25519, JWT, OTK, roles                        │
+│  PLATFORM (aimeat.io on the Core)                           │
+│  Apps + grants + origin isolation · agent fleet plane ·     │
+│  extensions/cortex · metered AI · scheduler · workflows ·   │
+│  skills & capabilities                                      │
+╞═════════════════════════════════════════════════════════════╡
+│  CORE — Federation    cross-node identity/login, peering    │
+│  CORE — Collaboration organisms, workspaces, knowledge      │
+│  CORE — Economy       morsels + USD metering ledger, trust  │
+│  CORE — Authorization consent, access-guard, IAM, delegation│
+│  CORE — Data          memory, storage, schema-lock          │
+│  CORE — Identity      GHII / GAII / GEAI, Ed25519, JWT       │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-Layers 1-2 are mandatory. Layers 3-5 are recommended but optional for specialized nodes.
+A node MUST implement Identity, Data, and Authorization. Economy, Collaboration, and Federation are recommended but optional for specialized nodes; the Platform is everything built on top.
 
 ### Design principles
 
@@ -117,7 +121,7 @@ Layers 1-2 are mandatory. Layers 3-5 are recommended but optional for specialize
 3. Self-bootstrapping, an AI can read a URL and integrate itself
 4. Fully decentralized, no single point of control
 5. Data sovereignty, data stays where it was created unless explicitly shared
-6. Economically self-regulating, morsel system with built-in burn mechanism
+6. Economically self-regulating, morsels gate low-value writes; real cost is metered separately (payment stays optional and operator-owned)
 
 ### Applications and packages
 
@@ -128,7 +132,7 @@ On top of the protocol sits the application layer. Apps are self-contained HTML
 | Type | Storage | Federation | Use case |
 |------|---------|------------|----------|
 | Full | Persistent (any backend) | Full | Primary node, implements the complete protocol |
-| Relay | In-memory only | Routing only | Stateless router, validates JWT and forwards requests |
+| Relay | Ephemeral (SQLite `:memory:`) | Routing only | Stateless router, validates JWT and forwards requests |
 | Mirror | Read-replica | Receive only | Geographic distribution and redundancy |
 | Personal | Local (SQLite) | Via parent node | Your own node on your own machine, tunnels through a full node |
 
@@ -137,9 +141,10 @@ On top of the protocol sits the application layer. Apps are self-contained HTML
 | Tier | Name | Auth | Who uses it |
 |------|------|------|-------------|
 | 0 | Browse | None (GET only) | Browsers, free-tier AI, humans |
-| 0.5 | Keyed Browse | One-Time Key in URL | AI platforms with limited HTTP (writes via GET) |
-| 1 | Agent | JWT Bearer token or MCP | AI agents with code execution or MCP connectors |
-| 2 | Operator | JWT with operator role | Node administrators |
+| 1 | Agent / Ecosystem app | JWT (device auth) or MCP | AI agents (GAII) and ecosystem apps (GEAI) |
+| 2 | Owner / Operator | Owner session / operator role | Humans over their own data; node administrators |
+
+*(The old Tier 0.5 keyed-browse / one-time-key path is deprecated — superseded by MCP + device authorization.)*
 
 ---
 
@@ -164,7 +169,7 @@ For MCP-capable runtimes (Claude Desktop, MCP-aware IDEs), run `aimeat connect s
 
 **Multi-agent connector.** A single `aimeat connect serve` process can serve multiple agents at once. Add more agents with `aimeat connect add --agent <name> --url ... --owner ...`; list them with `aimeat connect list`; remove with `aimeat connect remove <name>`. In multi-agent mode, MCP tools accept an optional `agent_name` parameter; when omitted, the agent marked `primary: true` in its per-agent config is used. This is the path for connecting one interactive agent (Claude Code) plus several **task-runner** agents (e.g. CrewAI crews) from one connector process -- see [docs/integrations/crewai.md](docs/integrations/crewai.md) for the task-runner pattern.
 
-**Agent modes.** Every agent declares a mode at registration: `autonomous` (continuous), `interactive` (chat/IDE, default), `task-runner` (triggered, runs one task, exits), `coordinator` (orchestrates others), or `workstation` (a node-visiting agent that lives in the user's own environment -- VSCode, Claude Desktop -- and uses MCP directly). Mode picks the Hello Integration flow: `task-runner` agents get a reduced 7-step onboarding (no command surface, but the test-task pair is kept as a smoke test), and `workstation` agents get the narrowest 4-step flow (auth + platform + capabilities + directives) because they are not node-resident -- no runtime config, slash commands, telemetry, or task queue. The others run the full 13 steps. Combine modes with owner-managed **tags** (`crew:*`, `source:*`, `role:*`, `project:*`) for filtering and grouping in the profile UI. Details: [docs/coding-guidelines/agent-tags.md](docs/coding-guidelines/agent-tags.md).
+**Agent modes.** Every agent declares a mode at registration: `autonomous` (continuous), `interactive` (chat/IDE, default), `task-runner` (triggered, runs one task, exits), `coordinator` (orchestrates others), or `workstation` (a node-visiting agent that lives in the user's own environment -- VSCode, Claude Desktop -- and uses MCP directly). Mode picks the Hello Integration flow: `task-runner` agents get a reduced 7-step onboarding (no command surface, but the test-task pair is kept as a smoke test), and `workstation` agents get the narrowest 4-step flow (auth + platform + capabilities + directives) because they are not node-resident -- no runtime config, slash commands, telemetry, or task queue. The others run the full 16-step flow (12 required + 4 optional). Combine modes with owner-managed **tags** (`crew:*`, `source:*`, `role:*`, `project:*`) for filtering and grouping in the profile UI. Details: [docs/coding-guidelines/agent-tags.md](docs/coding-guidelines/agent-tags.md).
 
 **2. Copy the prompt from your profile.** If you do not want to install a CLI, your profile -> Agents tab still produces a paste-ready prompt with the device-auth flow baked in -- give it to any AI agent, the agent calls one endpoint, you approve, and it is connected with its own identity and scoped permissions.
 
@@ -422,11 +427,35 @@ CI). Developer docs: [aimeat-desktop/README.md](aimeat-desktop/README.md).
 
 ## Reference Implementation
 
-The `aimeat/` directory contains a full reference implementation in TypeScript (Express 5.2, Node 24). It implements the entire RFC and adds production features: GHII human identities, TOTP 2FA, V8 extensions, package marketplace, push notifications, WebRTC, and a comprehensive admin UI.
+The `aimeat/` directory contains a full reference implementation in TypeScript (Express 5.2, Node 24). It implements the Core protocol and the Platform on top: GHII/GEAI identities + TOTP 2FA, organisms/workspaces, the app platform with scoped grants and origin isolation, the agent fleet plane, **QuickJS-WASM sandboxed extensions** + cortex, skills/capabilities, a package marketplace, push notifications, WebRTC, and a comprehensive operator admin dashboard.
+
+Three storage backends: SQLite (personal nodes, local dev; run `:memory:` for true in-RAM speed), MongoDB (production), and PostgreSQL (production) — the two Prisma backends carry separate schemas/clients. The legacy pure in-memory backend is deprecated -- SQLite `:memory:` covers the fast-iteration role using the actual production code path.
+
+See the [v4.0 Platform spec](docs/AIMEAT-RFC-v4.0-Platform-full.md) for everything built on the Core.
 
-Three storage backends: SQLite (personal nodes, local dev; can run `:memory:` for true in-RAM speed), MongoDB (production), and PostgreSQL (production). MongoDB and PostgreSQL share one Prisma-backed code path, so behaviour is identical across both. The legacy in-memory backend is deprecated -- SQLite `:memory:` covers the same fast-iteration role using the actual production code path.
+### Repository structure
+
+```
+aimeat-protocol/
+├── openapi.yaml              canonical API contract (OpenAPI 3.1)
+├── startup.prompt.md         paste-to-AI: fresh clone → running node
+├── aimeat/                   ★ the reference implementation (Node 24 / TypeScript / Express 5)
+│   ├── src/routes/           ~132 route handlers (one per domain)
+│   ├── src/services/         ~184 business-logic services
+│   ├── src/storage/          Storage interface + SQLite / MongoDB / PostgreSQL providers
+│   ├── src/auth/  mcp/  middleware/  models/  server-bootstrap/  cli/  enterprise/
+│   ├── public/               Preact + HTM SPA, no build (views, components, js, css, lib)
+│   ├── prisma/               schema.prisma (Mongo) + schema.postgres.prisma
+│   ├── locales/  test/  tools/   i18n · E2E suites · dev tools (synthtraces)
+│   └── docs/                  implementation-local docs (integrations, …)
+├── python/aimeat-crewai/     ★ pip-installable CrewAI liaison/connector (own PyPI line)
+├── aimeat-desktop/           ★ Tauri desktop app — AIMEAT Personal Node installer
+├── packages/                 hosted app source (agent-kanban, digital-signage, …) + build scripts
+├── assets/                   brand/design assets, logos, screenshots
+└── docs/                     spec + guides — v4.0 Core/Platform, coding-guidelines/, known_gaps, …
+```
 
-See the [Implementation Guide v3.0](docs/AIMEAT-IO-Implementation-Guide-v3.0.md) for full details.
+The agent **runtime** (fleet daemon + 40+ crew templates) lives in the sibling repo `miikkij/crewaimeat`; `aimeat-desktop` installs those agents to your machine and connects them via Hello Integration. Full subsystem map: [architecture guide](docs/coding-guidelines/architecture.md).
 
 ### Testing
 
@@ -452,12 +481,12 @@ cd aimeat && pnpm exec node --env-file=.env.test.sqlite --import tsx test/run-e2
 
 ## Documentation
 
-- [RFC v3.0](docs/AIMEAT-RFC-v3.0-full.md) - complete protocol specification
-- [Implementation Guide v3.0](docs/AIMEAT-IO-Implementation-Guide-v3.0.md) - everything beyond the spec
-- [OpenAPI spec](openapi.yaml) - machine-readable API contract (OpenAPI 3.1)
-- [Endpoint reference](docs/a-endpoints.md) - quick lookup
-- [Configuration](docs/b-config.md) - all node config options
-- [Platform compatibility](docs/c-platform-notes.md) - which AI platforms work at which tier
+- [RFC v4.0 — Core](docs/AIMEAT-RFC-v4.0-Core-full.md) - the generic, federatable protocol
+- [RFC v4.0 — Platform](docs/AIMEAT-RFC-v4.0-Platform-full.md) - what aimeat.io builds on the Core
+- [OpenAPI spec](openapi.yaml) - machine-readable API contract (OpenAPI 3.1, canonical)
+- [Architecture guide](docs/coding-guidelines/architecture.md) - subsystems + repository map
+- [Endpoint reference](docs/a-endpoints.md) · [Configuration](docs/b-config.md) · [Platform compatibility](docs/c-platform-notes.md)
+- [Build an AIMEAT-compatible agent](docs/building-an-aimeat-compatible-agent.md) · [ecosystem app](docs/building-an-aimeat-compatible-ecosystem-app.md)
 
 ---
 
@@ -465,6 +494,7 @@ cd aimeat && pnpm exec node --env-file=.env.test.sqlite --import tsx test/run-e2
 
 | Version | Date | Highlights |
 |---------|------|------------|
+| v4.0 | 2026-07-12 | Two-layer Core/Platform re-baseline; GEAI ecosystem apps; organisms/workspaces, app grants, agent fleet plane, skills/capabilities, metering ledger made first-class; economy = meters not one currency; micro-memory/OTK/boards/Foundry deprecated |
 | v3.0 | 2026-03-18 | Package system, device auth (RFC 8628), SSE, permissions |
 | v2.0 | 2026-03-08 | Node types, moderation, idempotency |
 | v1.x | 2025-2026 | Core protocol and early features |

package/dist/.env.example

@@ -285,6 +285,19 @@ AIMEAT_PORT=40050
 # AIMEAT_MARKETPLACE_TX_FEE_PERCENT=5       # Transaction fee percentage (buyer pays)
 # AIMEAT_MARKETPLACE_ESCROW=true            # Enable escrow for purchases
 
+# ── Commerce core + fee policy (TARGET-033) ───────────────────
+# AIMEAT_MARKETPLACE_FEE_MODE=operator      # Fee destination: operator (credit node operator) | burn (remove from supply)
+# AIMEAT_OPERATOR_FEE_ACCOUNT=              # Owner name receiving operator-mode fees (empty = first operator-role owner)
+# AIMEAT_COMMERCE_FEE_PERCENT=              # Checkout fee % (empty inherits AIMEAT_MARKETPLACE_TX_FEE_PERCENT)
+# AIMEAT_COMMERCE_ENABLED=true              # Checkout sessions (/v1/commerce) + UCP checkout capability
+# AIMEAT_COMMERCE_SESSION_TTL_MINUTES=60    # Open checkout-session lifetime
+# AIMEAT_MCP_CARD_COMMERCE_TOOLS=inline     # /.well-known/mcp.json commerce_tools block: inline (embed the priced app-tool catalog) | pointer (lean card linking /v1/commerce/tools)
+# AIMEAT_PLATFORM_STRIPE_KEY=              # Operator's OWN Stripe Connect platform secret (EE) — takes the platform application-fee on money sales; NOT custody (direct charges land on the seller)
+
+# ── Crawlers / Content Signals / Web Bot Auth ──────────────────
+# AIMEAT_WEB_BOT_AUTH_SIGN=false           # Sign outbound HTTP (RFC 9421 Web Bot Auth, node Ed25519 key) so peers/CDNs can verify AIMEAT traffic against /.well-known/http-message-signatures-directory. OFF by default: stamps identifying Signature headers on every outbound request (linkability; rare strict endpoints may reject unknown headers). The key directory is always served.
+# AIMEAT_CONTENT_SIGNAL="search=yes, ai-input=yes, ai-train=no"   # robots.txt Content Signals Policy directive (contentsignals.org). Keep consistent with the per-bot rules in public/robots.txt; 'off' removes the directive.
+
 # ── IndexNow (Bing/Yandex search indexing) ─────────────────────
 # Generate a key: openssl rand -hex 16
 # After setting, run: pnpm indexnow