Per-User Buchhaltung: Einnahmen & Ausgaben, Belege, USt-Voranmeldung und DATEV-CSV-Export. Integriert lesend mit dem payments-Addon (bezahlte Rechnungen fließen als steuerpflichtige Erlöse in die USt ein, ohne payments zu verändern). Lokale SQLite ist die Quelle der Wahrheit (ADR-054).
\naccounting/addons/accountingKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| POST | /api/v1/addons/accounting/datev |
| GET, POST | /api/v1/addons/accounting/receipts |
| GET | /api/v1/addons/accounting/reports |
| GET, POST | /api/v1/addons/accounting/transactions |
| DELETE | /api/v1/addons/accounting/transactions/[id] |
| GET | /api/v1/addons/accounting/vat |
", "byteSize": 1197 } } }, { "id": "aiopta-base-skill", "uuid": "ebbb02af-670b-49a4-811b-9990e9da2420", "name": "Aiopta Basisskill", "version": "1.2.1", "description": "Versioned, secret-free meta-skill that every newly created agent receives across UI, API, Template, Onboarding and Import/Seed creation paths. Single canonical source of truth for auth API, error handling, permission request and MCP tool usage — never re-implemented per controller (issues #105, #398).", "author": "Aiopta", "icon": "🧩", "capabilities": [ "agent-skills", "base-skill", "meta-skill" ], "tags": [], "download": "/artifacts/aiopta-base-skill-1.2.1.zip", "sha256": "cda43ffd26d8ba9d2f2f245d53efa4e48e28f02f3f8bf052f904a88be9bf1404", "size": 25355, "page": null, "deprecated": false, "endpoints": [], "skills": [ { "name": "aiopta-base", "displayName": "Aiopta Base Skill (meta)", "description": "Versioned, secret-free meta-skill: describes how the agent authenticates against the Aiopta API, how it reports errors, how it requests permissions and how it discovers and uses MCP tools — both addon-delivered servers and the three core-MCP surfaces (read-only, mutating, and the dedicated Tier-3 surface for sensitive/destructive tools) — including the permission-denied contract. Reused across UI / API / Template / Onboarding / Import / Seed creation paths; existing agents are migrated idempotently to the latest version (issues #105, #398). Meta-skill — declares no executable scripts and no addon-specific endpoint.", "permissions": [], "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
This addon is the single versioned source of truth for the
Aiopta Basisskill — the secret-free meta-skill that every newly created
agent receives across UI / API / Template / Onboarding / Import / Seed
creation paths.
| Property | Value |
|----------|-------|
| Addon id | aiopta-base-skill |
| Skill name | aiopta-base |
| Current version | 1.2.0 |
| Skill scripts | none (meta-skill, not a capability) |
| Endpoint | none (no runtime, doc-only descriptor) |
| Secrets / tokens | none — explicitly forbidden by the validator |
| Hard-coded URLs | none — agent fills the instance URL from its own config |
Without a canonical base skill, each agent-creation controller (UI form,POST /api/v1/agents, template clone, onboarding wizard, seed import)
would have to hand-roll its own auth/error/permission boilerplate. That
guarantees drift — one controller forgets to forward the bearer token,
another forgets to translate a 429 into a retry, and the agents stop
behaving consistently.
The base skill ships the description of how an agent authenticates,
handles errors, asks for permissions and uses MCP tools. The agent (a
separate runtime,
out of scope for this addon) consumes that description and renders it
into the same prompt / system-message across every creation path.
Existing agents are migrated idempotently: the migration script
(scripts/migrate-base-skill.cjs) reads the addon catalog, compares
the on-file version against the version each agent was provisioned
with, and either upgrades the reference or leaves the agent untouched
(user customisations are never overwritten — see the
Migration section below).
The single skills[] entry on this addon (name: aiopta-base) carries
the documented behaviour. It is a descriptor only — no scripts, no
endpoint, no runtime. The descriptor is consumed by core'ssrc/lib/agents/provision.ts (linked Core-PR, out of scope for this
addon repo).
Four things the descriptor specifies (see SKILL.md for the full text
the agent actually receives):
1. Auth API — every agent calls the Aiopta API with
Authorization: Bearer <its own key>, never with an addon secret.
The key is per-agent and provisioned by the canonical
createAgent(...) helper on the core side, not by this addon.
2. Error handling — 4xx is reported verbatim (status + body);
429 triggers a single retry with exponential backoff (max 3);
5xx is surfaced to the user with the request trace id; no silent
fallback that hides a permanent failure.
3. Permission request — the agent enumerates the permissions it
needs before the first call, asks the user once, and stores the
answer in the agent's permission record. Per-call 403 is treated
as "permission missing → request it", never as a fatal error.
4. MCP tools (issue #398) — the agent uses only the MCP tools that
core projects into its tool registry (capability-filtered,
aiopta-core#417). This covers both addon-delivered servers and the
three shipped core-MCP surfaces (aiopta-core#467/#468/#480,
docs/CORE-MCP.md): mcp:core:read:* (15 read-only tools),
mcp:core:write:* (11 mutating tools) and the dedicated Tier-3
surface mcp:core:tier3:* (4 sensitive/destructive tools). §4.4 of
SKILL.md documents the surface, that destructive/Tier-3 tools need an
exact core/… grant (no wildcard), and that the permission-denied
contract for core tools equals §4.3 — a denied core call is never
retried, escalated, or side-stepped via the raw route; the agent
informs the user once and stops.
# Verify (default — read-only, exits non-zero if invariants violated)\n./scripts/migrate-base-skill.sh --check# Apply (idempotent — second run reports "no change")
./scripts/migrate-base-skill.sh --apply
```
The script:
\n1. Reads addons/aiopta-base-skill/addon.json and confirms the skill
shape (one skill, no scripts, no endpoint, secret-free).
2. Reads SKILL.md and runs the secret / URL / host literal guard.
3. Reads dist/marketplace/catalog.json (if present) and confirms the
base skill is discoverable under id aiopta-base-skill.
4. Writes the current "applied" state to
dist/migrate-base-skill.json. A subsequent run with the same
inputs is a no-op.
On the addons repo the migration is purely catalog-side: the source
of truth for "which base-skill version is current" is this addon'saddon.json. On the core repo (out of scope) the same script is
invoked from src/lib/agents/provision.ts to backfill existing agents.
The catalog entry for this addon (built by npm run build:catalog)
exposes the version under addons[].version. The core API surfaces
the same version per agent underGET /api/v1/agents/:id → skills[][].addonVersion, so an operator can
always tell which base-skill a given agent is running.
The base skill must NEVER contain:
\n- API keys, bearer tokens, OAuth refresh tokens, basic-auth credentials
of any shape (the validator scans the descriptor body for these).
- Hard-coded instance URLs (the agent fills the URL from its own
config; baking one in would tie every agent to a single deployment).
- Hard-coded host names or IPs (same reason).
- Addon-specific skills (the base skill is meta — it points the agent
at the per-addon skill, it does not embed one).
- Duplicates — there is exactly one base skill version active at any
time; older versions are upgraded, not stacked.
All notable changes to the Aiopta Basisskill are documented here. The base
skill follows semantic versioning: a MAJOR bump means every agent must be
re-provisioned (auth API or permission model changed), a MINOR bump means
advisable but non-breaking (a new §3 rule, a new error class), a PATCH bump
means documentation / typo fixes only.
MINOR — advisable but non-breaking. Existing agents are upgraded idempotently
via scripts/migrate-base-skill.sh --apply (the #105 hook); user
customisations are never overwritten.
- §4 now documents the concrete core-MCP tool surface (the generic §4
from 1.1.0 said "once it ships" — it has now shipped: aiopta-core
#467/#468/#480 are merged, docs/CORE-MCP.md + ADR-075). New §4.4
"Core-MCP tools (Aiopta itself, shipped)":
- The three core surfaces and their tool-id namespaces —
mcp:core:read:* (15 read-only tools, #467), mcp:core:write:*
(11 mutating tools, #468) and the dedicated Tier-3 surface
mcp:core:tier3:* (4 sensitive/destructive tools, #480). Reserved
addon id core; each tool is a thin wrapper over one existing Aiopta
route.
- How the agent discovers/uses them: identical to any addon MCP tool
(§4.1–§4.3) — projected into the registry capability-filtered, called by
id, never probed/spawned, inputs carry no credential/URL/identity.
- Why some core tools are harder to obtain: destructive write tools need
the exact core/… grant verbatim (no */core/*), and every Tier-3
tool needs its own exact capability (a mcp:core:write grant unlocks
none) and is owner-only to delegate.
- The permission-denied contract for core tools is the §4.3 contract,
stated explicitly for the core surface: a denied/not_available core
result is never retried, never escalated, never side-stepped via the raw
/api/v1/... route, and never worked around by obtaining a
destructive/Tier-3 grant — the agent informs the user once and stops.
Core enforces server-side on every call and audits denials + every
mutation (core.mcp.tool.denied / core.mcp.tool.ok).
- Unchanged: auth API (§1), error handling (§2), permission request (§3),
the addon-MCP rules (§4.1–§4.3) and the domain rule — no hard-coded
URLs/hosts; the agent fills the instance URL from its own runtime config.
- EXPECTED_BASESKILL_VERSION bumped to 1.2.0 in
scripts/migrate-base-skill.cjs.
MINOR — advisable but non-breaking. Existing agents are upgraded idempotently
via scripts/migrate-base-skill.sh --apply (the #105 hook); user
customisations are never overwritten.
- New §4 "MCP tools (addon-delivered and core)": how the agent discovers
addon-delivered MCP tools (capability-filtered projection into the
canonical tool registry, aiopta-core#417), how it uses them (server-side
re-authorization per call, fail-closed, no credentials/URLs in tool
arguments), and that the core-MCP (aiopta-core#466/#467) follows exactly
the same rules once it ships.
- New §4.3 permission-denied contract: a denied MCP tool call is never
retried, never escalated or worked around via another tool; the agent
informs the user once and stops attempting the call.
- Renamed the legacy "Aiopta API" wording to "Aiopta API" (naming only, no
semantic change).
- Sections renumbered: Provenance is now §5, Hard-negative scope is now §6.
- Unchanged: auth API (§1), error handling (§2), permission request (§3)
and the domain rule — no hard-coded URLs/hosts; the agent fills the
instance URL from its own runtime config.
- EXPECTED_BASESKILL_VERSION bumped to 1.1.0 in
scripts/migrate-base-skill.cjs.
Initial release. Defines the single, versioned, secret-free Aiopta Basisskill:
\n- One skill descriptor: name: aiopta-base, no scripts, no endpoint, no
permissions of its own (meta-skill).
- Three documented behaviours: auth API, error handling, permission request.
- Hard-negative scope (validator-enforced): no secrets, no hard-coded URLs,
no hard-coded hosts, no addon-specific skills, no scripts.
- Migration script scripts/migrate-base-skill.cjs (+ .sh wrapper + tests)
for idempotent backfill of existing agents and upgrade on version bumps.
- Catalog entry under id aiopta-base-skill for marketplace discovery.
Usage analytics, cost tracking, performance metrics, report generation, and a central
Observability-Dashboard (C5, ADR-033).
analytics/analytics (Tab Observability für Nutzung/Kosten/Fehler/Kontingent)Keine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/analytics/activity |
| GET | /api/v1/addons/analytics/costs |
| GET | /api/v1/addons/analytics/dashboard |
| GET, POST | /api/v1/addons/analytics/events |
| GET | /api/v1/addons/analytics/observability |
| GET | /api/v1/addons/analytics/performance |
| GET, POST | /api/v1/addons/analytics/reports |
| GET, PUT, DELETE | /api/v1/addons/analytics/reports/[id] |
| GET | /api/v1/addons/analytics/reports/export |
Zentrale, read-only Aggregation bereits vorhandener Daten über einen wählbaren Zeitraum
(24 h / 7 / 30 / 90 Tage):
- Agenten-/LLM-Nutzung — Anzahl + Token-Schätzung aus Phase-Q usage_counters.
- Kosten — aus den erfassten cost_entries (klar als Schätzung markiert, keine Abrechnung).
- Fehler/Aktivität — aus dem audit_log, gruppiert nach action (die Tabelle hat keine
Severity-Spalte → Fehler werden anhand des Aktionsnamens erkannt, z. B. *.failed/*.denied).
- Kontingent-Status — Verbrauch vs. Tarif-Limit aus den Entitlements/Quotas.
Scope ist rollenbewusst: ein normaler Benutzer sieht nur eigene Daten, ein Admin standardmäßig die
ganze Instanz (mit Opt-down auf ?scope=user). Die Route ist die Autorität — ein Benutzer kann den
Scope nicht erweitern. KPIs, Charts (hand-gezeichnetes SVG/CSS — keine neue Charting-Dependency) und
Tabellen. Server liest getDb; die Tab-Komponente nutzt ausschließlich apiFetch (kein getDb/fs im
Client). SQL ist durchgehend parametrisiert; es werden keine Secrets gelesen oder geloggt.
# Instanzweit (Admin), 30-Tage-Fenster\ncurl -s -H "Authorization: Bearer $AIOPTA_API_KEY" \\\n "https://<instance>/api/v1/addons/analytics/observability?scope=instance&windowDays=30"# Nur eigene Daten
curl -s -H "Authorization: Bearer $AIOPTA_API_KEY" \\
"https://<instance>/api/v1/addons/analytics/observability?scope=user&windowDays=7"
```
Zusätzlich zum direkten Schreibpfad (POST /events → recordUsageEvent) speist analytics
Agent-Aktivitäts-Metriken passiv über den in-process Event-Bus: der Collector
(src/lib/activity-collector.ts) abonniert lazy + idempotent im Addon-install() (globalThis-
Singleton, kein Boot-Hook — spiegelt den artefakt-workspace-Collector) und schreibt für jedes
Agent-Output-Event eine per-User-usage_events-Zeile (event_type='agent.activity'), sobald es
passiert. So füllen sich die bestehenden Dashboard-Metriken (Top-Agenten, Trends) aus echter
Agent-Aktivität — additiv, die Bestandspfade bleiben unverändert.
- Abonnierte Events: agent.output.produced (kanonisches generisches Signal) und
development.session.completed (trägt userId + status). Ein fehlgeschlagener Run
wird als Error markiert (metadata.isError).
- Ownership (ADR-054): der Besitzer kommt IMMER aus dem Event-Payload (userId/user_id/
ownerId), NIE aus einem Client-Wert; ein Event ohne erkennbaren User wird übersprungen
(geloggt), nicht geraten. Der Write läuft über scopedStore(userId) ⇒ user_id server-seitig
erzwungen.
- Per-User-Feed: GET /api/v1/addons/analytics/activity (userRoute) liefert die eigenen
agent.activity-Zeilen (Filter event_type/agent_id + Pagination); B's Aktivität erscheint nie
in A's Feed. Die instanzweiten Aggregate (dashboard/observability) bleiben admin-gegated.
- Gap (Park-Kandidat): business-operator.action.queued und payments.invoice.paid tragen keinen
User-Owner und werden nicht abonniert (per-User-Recording würde einen Owner erfinden — ADR-054-
verboten). Per-User-Attribution erfordert eine additive Emit-Anreicherung an der Quelle (Owner-
Entscheidung). agent.output.produced hat noch keinen in-tree-Emitter (Vorwärts-Signal).
# Eigener Agent-Aktivitäts-Feed (event-getrieben)\ncurl -s -H "Authorization: Bearer $AIOPTA_API_KEY" \\\n "https://<instance>/api/v1/addons/analytics/activity?page=1&page_size=60"- Kosten = Schätzung aus erfassten Nutzungsdaten, keine abgerechnete Summe (präzises Pricing geparkt,
OPEN-DECISIONS #52).
- Fehler werden heuristisch aus dem Aktionsnamen im audit_log abgeleitet (keine Severity-Spalte).
- Nutzungszähler sind Fenster-Buckets (Tag/Monat/lifetime) → die Nutzung spiegelt die aktuellen
Zähler, nicht einen beliebigen historischen Bereich.
- Kein Export zu externen Observability-/APM-Systemen (Prometheus/Grafana/Datadog) — geparkt
(OPEN-DECISIONS #51).
A typed, auto-collected gallery of ALL agent outputs. The addon subscribes to the in-process
event-bus (ADR-053) and turns every produced agent output into a per-user artefact — passively, with
zero manual upload — then presents a filterable grid to view, open, and delete.
artefakt-workspace/addons/artefakt-workspace (Bereich: Data)1. Ein Agent erzeugt einen Output (z. B. eine Coding-Session läuft fertig).
2. Der Emitter publiziert ein Event auf dem in-process Event-Bus, das die erzeugende userId
(server-seitig gestempelt) und den Output trägt.
3. Der Collector (src/lib/collector.ts) abonniert die Agent-Output-Events, klassifiziert den
Output nach Typ und legt eine Artefakt-Zeile an — gestempelt auf den erzeugenden User.
4. Die Galerie zeigt jedem User nur seine eigenen Artefakte.
Abonnierte Events:
\n| Event | Quelle | Trägt |
|---|---|---|
| agent.output.produced | beliebig (kanonisches Signal) | userId + Output (content/url/path/kind/mime/title) |
| development.session.completed | development | userId + result/text (additiv ergänzt, #148) |
\nOwnership-Regel (ADR-054): Der Besitzer kommt IMMER aus dem Event-Payload-User-Context
(
userId/user_id/ownerId) — nie aus einem Client-Wert. Ein Event ohne erkennbaren User wirdübersprungen (geloggt), nicht geraten.
Sechs Typen, first-match-wins (am spezifischsten → am allgemeinsten):
\n| Typ | Erkannt an |
|---|---|
| image 🖼️ | Image-MIME, oder url/path mit Bild-Endung |
| file 📄 | ein path-Verweis, eine Quelldatei-url, oder ein nicht-Bild-Binär-MIME |
| code 💻 | ein language-Hinweis oder ein ``` ` ```-Codeblock |
| text 📝 | Fallback für Prosa |
| link 🔗 | eine nackte http(s)-url |
| data 📊 | Inhalt, der als JSON-Objekt/Array parst |
Ein expliziter, gültiger kind-Hinweis im Payload gewinnt immer über die Inferenz.
Basis: /api/v1/addons/artefakt-workspace. Auth: Aiopta-API-Key
(-H "Authorization: Bearer $AIOPTA_API_KEY"). Antworten: { success, data | error }.
| Methode(n) | Pfad | Zweck |
|---|---|---|
| GET | /api/v1/addons/artefakt-workspace | Eigene Artefakte listen (Filter: type, source, since, until, page, page_size) |
| GET | /api/v1/addons/artefakt-workspace/facets | Pro-Typ-Zähler + Quellen-Liste für die Filterleiste |
| GET | /api/v1/addons/artefakt-workspace/[id] | Ein eigenes Artefakt holen (fremde/unbekannte id → 404) |
| DELETE | /api/v1/addons/artefakt-workspace/[id] | Ein eigenes Artefakt löschen (owner-scoped; fremd → 404) |
# Eigene Code-Artefakte der letzten Woche listen\ncurl -s -H "Authorization: Bearer $AIOPTA_API_KEY" \\\n "https://<instance>/api/v1/addons/artefakt-workspace?type=code&since=2026-06-09"# Facetten (für die Filter-Chips)
curl -s -H "Authorization: Bearer $AIOPTA_API_KEY" \\
"https://<instance>/api/v1/addons/artefakt-workspace/facets"
# Ein Artefakt löschen
curl -s -X DELETE -H "Authorization: Bearer $AIOPTA_API_KEY" \\
"https://<instance>/api/v1/addons/artefakt-workspace/<id>"
```
- Per-User isoliert (ADR-054): Jedes Artefakt gehört dem erzeugenden User; addon_artefacts
trägt user_id TEXT NOT NULL, jeder Zugriff läuft über scopedStore(userId). Man sieht und
löscht nur die EIGENEN Artefakte; eine fremde/unbekannte {id} liefert 404 (nie 403, nie die
fremde Zeile).
- Route-Auth (ADR-056): Alle Routen sind userRoute/ownedResourceRoute-gewrappt; die
Lösch-Mutation ist owner-scoped.
- Keine Blobs / kein FS-Write: Es werden nur Metadaten + eine Referenz (url/path) und ein
gekappter Inhalts-Vorschautext (max. 20 000 Zeichen) gespeichert.
Keine Secrets erforderlich — das Addon sammelt automatisch, sobald es installiert/aktiviert ist
(die Event-Bus-Subskription wird im install() lazy + idempotent aufgesetzt).
Full-instance backup + restore (C4, ADR-032).
\nbackups/backups (Admin-Sektion)An admin can create a full-instance backup, download it, and restore from a stored or uploaded archive.
A backup is a single ZIP containing a logical dump of every database table (includingapp_settings with its secret/license/config rows and all addon-local tables), the **files underDATA_DIR, and a manifest with a SHA-256 checksum**. The archive is built with a dependency-free
ZIP writer (Node zlib) and is read back by Aiopta's hardened, zip-slip/zip-bomb-safe extractor.
Backups are encrypted at rest (AES-256-GCM), can be copied off-site to an **S3, SFTP, or NAS
(WebDAV) remote target — and a restore can pull the archive back** from that target — are pruned by a
retention policy, and enabled schedules auto-fire on the durable in-process scheduler
(#124 + #138, ADR-032 addendum).
Funktioniert sofort ohne Credentials: das lokale Backup wird at-rest verschlüsselt mit einem
selbst-verwalteten 32-Byte-Schlüssel, der beim ersten Backup automatisch erzeugt und in der Addon-Config
als Secret (BACKUP_ENC_KEY, is_secret=1, maskiert, nie geloggt) abgelegt wird — kein Owner nötig.
Optional (Off-site, Owner-Creds, OPEN-DECISIONS #48) über PUT /api/v1/addons/backups/config bzw. die
Addon-Config:
| Key | Zweck |
|---|---|
| BACKUP_REMOTE_TYPE | none (Default) · s3 · sftp · nas |
| BACKUP_REMOTE_PATH | Key-/Pfad-Präfix im Ziel (Unterordner) |
| BACKUP_S3_BUCKET / BACKUP_S3_REGION / BACKUP_S3_ENDPOINT | S3-Ziel (Endpoint optional für S3-kompatibel) |
| BACKUP_S3_ACCESS_KEY_ID / BACKUP_S3_SECRET_ACCESS_KEY | S3-Creds (Secret) |
| BACKUP_SFTP_HOST / BACKUP_SFTP_PORT / BACKUP_SFTP_USERNAME | SFTP-Ziel |
| BACKUP_SFTP_PASSWORD / BACKUP_SFTP_PRIVATE_KEY | SFTP-Creds (Secret) |
| BACKUP_NAS_URL | NAS via WebDAV — Collection-Basis-URL (z. B. https://nas.local:5006/remote.php/dav/files/mc); Synology/QNAP/TrueNAS/Nextcloud, reines HTTP[S], keine neue Dependency |
| BACKUP_NAS_USERNAME / BACKUP_NAS_PASSWORD | NAS/WebDAV-Creds (Passwort Secret) |
| BACKUP_RETENTION_KEEP / BACKUP_RETENTION_DAYS | Retention (Default 10 / 30) |
Solange Creds fehlen ist das Remote-Ziel graceful inaktiv ("remote target not configured") — das
lokale (verschlüsselte) Backup läuft trotzdem, es gibt keinen Fake-Upload und keinen Crash. Alle Routen
sind admin-only (addon.manage), weil ein Backup naturgemäß Secret-Einstellungen enthält.
| Methode(n) | Pfad | Zweck |
|---|---|---|
| GET | /api/v1/addons/backups | Backups auflisten (admin) |
| POST | /api/v1/addons/backups | Voll-Backup erstellen — Body { name?, excludeSecrets? } (admin) |
| GET, DELETE | /api/v1/addons/backups/[id] | Backup-Metadaten / löschen (das letzte Backup ist geschützt) |
| GET | /api/v1/addons/backups/[id]/download | Archiv als Attachment streamen (admin) |
| POST | /api/v1/addons/backups/[id]/restore | Aus gespeichertem Backup wiederherstellen — Body { confirm: true } (admin, destruktiv) |
| POST | /api/v1/addons/backups/restore | Aus hochgeladenem Archiv wiederherstellen — multipart file + confirm=true (admin, destruktiv); dryRun=true validiert nur. Oder aus dem Remote-/NAS-Ziel ziehen — JSON-Body { remoteFile, confirm: true } (zieht zuerst, dann identischer Safe-Restore). Entschlüsselt verschlüsselte Archive automatisch |
| GET, PUT, POST | /api/v1/addons/backups/config | Config lesen (maskiert) / speichern; POST ?action=test-remote (Verbindungstest) · POST ?action=prune (Retention jetzt anwenden) (admin) |
| GET, POST | /api/v1/addons/backups/schedules | Backup-Zeitpläne auflisten/erstellen — Body akzeptiert interval_seconds? (admin) |
| GET, PATCH, DELETE | /api/v1/addons/backups/schedules/[id] | Zeitplan lesen/ändern/löschen (admin) |
- Destruktiv & abgesichert: Restore läuft nie implizit — explizites confirm erforderlich; das Manifest
+ die Prüfsumme + die Format-Version werden vor jedem Schreiben validiert; vorab wird ein
Pre-Restore-Safety-Snapshot des aktuellen Stands erstellt; die DB wird in einer Transaktion
(atomar) wiederhergestellt; die Extraktion ist zip-slip/zip-bomb-sicher (geteilter Extractor).
- Encryption-at-rest: Archive werden mit AES-256-GCM in einem authentifizierten Envelope
(MCBK1-Magic + IV + Auth-Tag) verschlüsselt; der 32-Byte-Schlüssel wird lazy erzeugt und als Secret
in der Addon-Config gehalten (nie geloggt). Rückwärtskompatibel: alte Plaintext-ZIPs werden weiter
restauriert; der Download entschlüsselt on-the-fly zu einem portablen ZIP.
- Secrets: Ein Backup enthält Secret-app_settings (Lizenz/Auth/Config) — deshalb sind alle Routen
admin-only und Secret-Werte (inkl. Backup-Key und Remote-Creds) werden nie geloggt.
excludeSecrets: true erzeugt einen bereinigten Dump (ohne is_secret-Zeilen). **Ein Restore
überschreibt auch die Secrets.**
- Retention: löscht nur Archive, die beide Fenster (Anzahl und Alter) verletzen, und **nie das
letzte verbleibende Backup**.
- Auto-Fire-Sicherheit: der Scheduler erstellt + pruned nur — ein **destruktiver Restore wird nie
automatisch ausgeführt**.
- Remote-Aktivierung wartet auf Owner-Creds (OPEN-DECISIONS #48 / Block H; das NAS-Ziel ist #138) —
Mechanismus + UI sind gebaut, das Ziel ist ohne Creds graceful inaktiv. ssh2 (SFTP) wird dynamisch
geladen; fehlt es, meldet der Upload "dependency missing" statt zu crashen. NAS nutzt WebDAV über den
globalen fetch (keine neue Dependency); Creds gehen nur in den Authorization: Basic …-Header und
werden nie geloggt/zurückgegeben.
- Cron mit fixer Uhrzeit: der durable Scheduler arbeitet intervallbasiert; Cron-Ausdrücke werden auf
eine feste Kadenz gemappt (stündlich/täglich/wöchentlich/alle-N-Min/Std), eine exakte Wall-Clock-Zeit
ist eine Folgearbeit (OPEN-DECISIONS #50, "simpel jetzt" wie der restliche Scheduler).
", "byteSize": 6388 } } }, { "id": "bahn-bet", "uuid": "cba4f478-4516-457d-986b-4ded28cf8e4a", "name": "BahnBet", "version": "1.0.6", "description": "Live BahnBet monitor for public train-delay markets, platform stats, and leaderboard highlights.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "train-delay-markets", "leaderboard", "web-scraping" ], "tags": [], "download": "/artifacts/bahn-bet-1.0.6.zip", "sha256": "6d920c998b26f7b86c73b29f4919d5e6f6e93ec783056a4decc92ba41f48b353", "size": 77639, "page": { "path": "/addons/bahn-bet", "name": "BahnBet", "icon": "🚆", "section": "Experiments", "component": "@addons/bahn-bet/src/components/BahnBetDashboard" }, "deprecated": false, "endpoints": [ "/api/v1/addons/bahn-bet/summary", "/api/v1/addons/bahn-bet/leaderboard" ], "skills": [], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "Siehe
docs/architecture/ADR-032-backup-restore.md(Addendum #124) undSKILL.md.
Live BahnBet monitor for public train-delay markets, platform stats, and leaderboard highlights.
\nbahn-bet/addons/bahn-betKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\nnpm-Abhängigkeiten (werden bei Installation aufgelöst): cheerio.
| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/bahn-bet/leaderboard |
| GET | /api/v1/addons/bahn-bet/status |
| GET | /api/v1/addons/bahn-bet/summary |
", "byteSize": 837 } } }, { "id": "blender", "uuid": "3c63ddcb-87fa-4b10-b516-8f7926ef8a9e", "name": "Blender", "version": "0.3.4", "description": "Agent-driven Blender via a BlenderMCP-style socket backend, fronted by a capability-enforcing Aiopta proxy (addons#815, core#1078 F2). Curated semantic tools (scene inspect/op, material, render, asset import/export) map to elevated dotted capabilities (addons.blender.scene.*/.asset.*); a separately gated raw-Python hatch (execute_blender_code) maps to the highest-tier addons.blender.python.exec. No raw passthrough: every tool call is gated against server-resolved grants and audited. Two backends: local-first (native-app bridge to the user's Blender on loopback :9876) and a headless sandbox container (workspace-only, no host network, render caps) for the safe autonomous path. Future/backlog — not dispatched until after the Enterprise-Clean programme (#1020).", "author": "Aiopta", "icon": "🧊", "capabilities": [ "blender", "3d", "rendering", "mcp", "agent-tools" ], "tags": [], "download": "/artifacts/blender-0.3.4.zip", "sha256": "f07e0c6aab66ee8ee96d7a98fbd1674bee89e48dc4c07652e4eeb4356e69c5ee", "size": 162839, "page": null, "deprecated": false, "endpoints": [], "skills": [], "mcpServers": [ { "id": "blender-tools", "displayName": "Blender tools", "description": "Capability-enforcing MCP proxy in front of a BlenderMCP-style socket backend (addons#815 / core#1078 F2). The agent never speaks the Blender socket protocol directly: it sees curated semantic tools (scene inspect/op, material, render, asset import/export) plus a separately gated raw-Python hatch. Each tool maps to a dotted capability (scene/asset = elevated, python/exec = highest); calls are gated against server-resolved grants (core#871 gateway seam, stubbed) and audited. Credentials for asset providers travel only via scoped tickets (addons#813), never as tool arguments. Local backend talks loopback-only; sandbox backend has no host network.", "transport": "stdio", "runtime": "node", "entry": "blender-tools/server.mjs", "permissions": [ "addons/blender/asset/export", "addons/blender/asset/import", "addons/blender/scene/op", "addons/blender/scene/read", "addons/blender/scene/render" ], "toolPolicy": { "mode": "write", "allowDestructive": false }, "configRefs": [ "mode" ], "credentialRefs": [ "sketchfabApiKey" ], "archiveEntry": "blender/mcp/servers/blender-tools/server.mjs", "sha256": "b53146b7547d898f8841c598860f7610cd159983de4f9b887ff7dadd4e221f10", "size": 30392, "descriptorVersion": 1 } ], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Agent-driven Blender über einen BlenderMCP-ähnlichen Socket-Backend, frontiert
durch einen capability-erzwingenden Aiopta-Proxy (addons#815, core#1078 F2).
Kuratierte semantische Werkzeuge (Szene inspizieren/ändern, Material, Render,
Asset-Import/Export) mappen auf elevated dotted Capabilities
(addons.blender.scene.*, addons.blender.asset.*); eine separat gegatete
Raw-Python-Klappe (execute_blender_code) mappt auf die Highest-Tier-Capabilityaddons.blender.python.exec. Kein Raw-Passthrough: Jeder Tool-Aufruf wird gegen
server-seitig aufgelöste Grants geprüft und auditiert.
blender/addons/blenderaiopta-blender-tools (kuratierte, capability-gegatete Tools)| Backend | Zweck | Netz |
|---|---|---|
| local | Native-App-Bridge zur Blender-Instanz des Nutzers (Loopback :9876) | nur loopback |
| sandbox | Headless-Sandbox-Container (workspace-only, kein Host-Netz, Render-Caps) für den sicheren autonomen Pfad | isoliert |
Der aktive Modus wird vom Proxy gemeldet (mode: local | sandbox) und ist pro
Aufruf sichtbar — der Sandbox-Pfad ist der sichere Standard für autonome
Abläufe.
Enforcement ist server-seitig und unabhängig davon, was ein Agent glaubt zu
dürfen (core#871):
addons.blender.scene.*, addons.blender.asset.* (kuratierte Tools)addons.blender.python.exec (Raw-Python-Klappe)Vor jeder Nutzung: blender_capabilities abfragen (ungated) — es liefert pro
Capability die Tier und ob sie für den aktuellen Caller effective ist.
BYOK: der local-Modus erwartet den BlenderMCP-Socket-Bridge auf Loopback:9876 (Native-App-Bridge zur Blender-Instanz des Nutzers). Der sandbox-Modus
braucht keine Host-Blender-Instanz — der Container rendert workspace-only.
- Future/Backlog-Features (erweiterte Szenen-Ops) werden erst nach dem
Enterprise-Clean-Programm (#1020) dispatched.
- Raw-Python (execute_blender_code) ist bewusst die Ausnahme — kuratierte
Tools sind der Standard-Workflow (siehe SKILL.md).
", "byteSize": 2361 } } }, { "id": "booking", "uuid": "603d9ba4-21d6-4cdb-b8e5-ef3c0536548d", "name": "Booking", "version": "1.0.3", "description": "Per-user booking addon: owner-configured bookable resources, weekly availability and time slots, a calendar of bookings, plus a public booking page where visitors pick an open slot and book — with confirmation/reminder emails.", "author": "Aiopta", "icon": "📆", "capabilities": [ "booking", "scheduling", "calendar" ], "tags": [], "download": "/artifacts/booking-1.0.3.zip", "sha256": "cd8ca59fc8185eb4fc2a7c014a2570b4c135369bac9ac8e807901b7b75460d63", "size": 132094, "page": null, "deprecated": false, "endpoints": [ "/api/v1/addons/booking" ], "skills": [ { "name": "booking-manage", "displayName": "Manage bookings", "description": "List, create and update the user's own bookable resources, availability and bookings.", "permissions": [ "addons/booking/read", "addons/booking/write" ], "endpoint": "/api/v1/addons/booking", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README manuell gepflegt (addon.json + Routen als Quelle).
Per-user booking for Aiopta (issue #485 / INBOX-5). An owner publishes
bookable resources with weekly availability; the addon computes concrete open
time slots and exposes a public booking page where external visitors pick a
slot and book. Confirmation (and reminder) emails are sent best-effort.
Built user-scoped from day one on the ADR-054 foundation: every durable record
carries user_id and is reached only through scopedStore(ownerId).
- Bookable resources (event types): name, slug, duration, buffer, active.
- Availability: weekly recurring windows per resource (weekday + start/end).
- Slots / calendar: open slots are computed from availability minus existing
bookings (buffer-aware), over a configurable horizon, with a minimum lead time.
- Public booking page: read-only listing of an owner's published resources +
open slots, and a constrained "create a pending booking" action.
- Confirmation / reminder emails: pure renderers + an SMTP transport (lazy
nodemailer, instance addon-config); reminder timing is computed (reminderDueAt)
for a cron/worker — the addon holds no live timers.
This is the security-critical boundary. Two distinct surfaces:
\n| Surface | Auth | Wrapper | Owner identity | What it can do |
| --- | --- | --- | --- | --- |
| Owner CRUD (resources, availability, bookings, settings) | authenticated | userRoute | auth.id (server) | full read/write of own data only |
| Public page (public/[owner], …/availability, …/book) | none | route | resolved from the public slug | read published slots; create one pending booking for that owner |
Key invariants:
\n1. The owner id is never taken from the request body. Owner CRUD stamps the
owner from auth.id; the public path resolves it from the public slug via
resolveOwnerByPublicSlug and forces it into createBooking. There is no
parameter by which a caller can write to a different owner.
2. The public path is not a cross-user write primitive. The only mutation an
anonymous visitor can perform is appending a pending booking to the single
owner the slug names, for a slot that owner published, validated against that
owner's availability + existing bookings, and bounded by a per-key sliding
rate limit. Owners review/confirm pending bookings via the authed CRUD.
3. No cross-user reads. The public projection exposes only active resources
and computed slots for the resolved owner — never another owner's data, never
private fields (resource ids, visitor PII of other bookings, owner id).
4. Unauthenticated reachability. The addon dispatch defers unauthenticated
callers to the route's own auth, so the public route()-wrapped endpoints are
reachable without a session while the owner endpoints require one.
5. resolveOwnerByPublicSlug is the only cross-user read — it returns just an
owner id from a public slug (no private data); everything after it is normal
owner-scoped access for that one resolved owner.
user_id-scoped, FK-free)booking_resources(id, user_id, slug, name, description, duration_minutes, buffer_minutes, active, …) — UNIQUE(user_id, slug)booking_availability(id, user_id, resource_id, weekday, start_minute, end_minute, …)booking_bookings(id, user_id, resource_id, booking_date, start_minute, end_minute, visitor_name, visitor_email, notes, status, source, …)booking_settings(user_id PK, public_slug UNIQUE, display_name, timezone, min_lead_minutes, horizon_days, accepting_bookings, …)The user_id column is intentionally FK-free (TEXT NOT NULL, noREFERENCES users(id)): a REFERENCES FK resolves at prepare time and throws on a
bare addon-only test DB. Ownership is enforced in SQL by the user-scope layer
regardless, and registerScopedTable is best-effort (try/catch).
Owner (authenticated):
- GET/POST /api/v1/addons/booking/resources, GET/PUT/DELETE …/resources/[id]
- GET/POST /api/v1/addons/booking/availability, DELETE …/availability/[id]
- GET/POST /api/v1/addons/booking/bookings, GET/PATCH/DELETE …/bookings/[id]
- GET/PUT /api/v1/addons/booking/settings (mail status is masked — no secret)
- GET /api/v1/addons/booking/status
Public (unauthenticated, keyed to the owner's public slug):
- GET /api/v1/addons/booking/public/[owner] — published resources + page meta
- GET /api/v1/addons/booking/public/[owner]/availability?resource=<slug> — open slots
- POST /api/v1/addons/booking/public/[owner]/book — create a pending booking
SMTP is read from instance addon-config (SMTP_HOST/PORT/USER/PASS/SECURE/FROM)
via getAddonConfiguration("booking"), never the manifest, never logged. The
settings/status endpoints expose only a masked view (presence flags + the
public From address).
Container-local browser automation addon with screenshot and page snapshot APIs.
\nbrowser/addons/browserKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\nnpm-Abhängigkeiten (werden bei Installation aufgelöst): puppeteer.
| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/browser/config |
| GET | /api/v1/addons/browser/health |
| POST | /api/v1/addons/browser/install-runtime |
| POST | /api/v1/addons/browser/screenshot |
| POST | /api/v1/addons/browser/snapshot |
| POST | /api/v1/addons/browser/start |
| GET | /api/v1/addons/browser/status |
| POST | /api/v1/addons/browser/stop |
", "byteSize": 1040 } } }, { "id": "budget", "uuid": "1f4a5e3f-8f9a-4f8a-8c3c-24a07f957465", "name": "Budget (Konten/Kategorien/Budgets/wiederkehrend/Charts)", "version": "1.2.1", "description": "Per-User Budgeting: Konten, Kategorien, Budgets, wiederkehrende Transaktionen und Charts (Ausgaben über Zeit, Kategorie-Aufschlüsselung, Budget vs Ist). Integriert lesend mit den trading- + payments-Addons (realisierte PnL / bezahlte Rechnungen fließen in die Reports), ohne diese zu verändern. Lokale SQLite ist die Quelle der Wahrheit (ADR-054).", "author": "Aiopta", "icon": "💰", "capabilities": [ "budget", "accounts", "categories", "budgets", "transactions", "recurring", "reports", "charts" ], "tags": [], "download": "/artifacts/budget-1.2.1.zip", "sha256": "113ccbaf904e20a625031b9b7fcd6b1f6b6c3ddb12dcd768509c91e4e2205578", "size": 198591, "page": { "id": "budget-page", "path": "/addons/budget", "name": "Budget", "icon": "💰", "section": "Money", "component": "@addons/budget/src/components/BudgetPage" }, "deprecated": false, "endpoints": [ "/api/v1/addons/budget/accounts", "/api/v1/addons/budget/accounts/:id", "/api/v1/addons/budget/categories", "/api/v1/addons/budget/categories/:id", "/api/v1/addons/budget/budgets", "/api/v1/addons/budget/budgets/:id", "/api/v1/addons/budget/transactions", "/api/v1/addons/budget/transactions/:id", "/api/v1/addons/budget/recurring", "/api/v1/addons/budget/recurring/:id", "/api/v1/addons/budget/reports/bundle", "/api/v1/addons/budget/reports/summary" ], "skills": [ { "name": "budget-read", "displayName": "Budget: Konten, Budgets & Reports lesen", "description": "Listet Konten, Kategorien, Budgets, Transaktionen und wiederkehrende Regeln des Nutzers sowie die Charts (Ausgaben über Zeit, Kategorie-Aufschlüsselung, Budget vs Ist). Reiner Lesezugriff — bucht nichts.", "permissions": [ "addons/budget/accounts", "addons/budget/categories", "addons/budget/budgets", "addons/budget/transactions", "addons/budget/recurring", "addons/budget/reports" ], "endpoint": "/api/v1/addons/budget/reports/bundle", "scripts": [] }, { "name": "budget-write", "displayName": "Budget: Transaktionen, Budgets & Regeln erfassen", "description": "Erfasst Konten, Kategorien, Budgets, Transaktionen und wiederkehrende Regeln für den Nutzer (per-User gebucht) und löscht diese.", "permissions": [ "addons/budget/accounts", "addons/budget/categories", "addons/budget/budgets", "addons/budget/transactions", "addons/budget/recurring" ], "endpoint": "/api/v1/addons/budget/transactions", "scripts": [] } ], "mcpServers": [ { "id": "budget-tools", "displayName": "Budget tools", "description": "Read-only budget report math for agents: spending over time, category breakdown, budget vs actual, account balances, recurring-rule expansion and money formatting — the same pure functions the budget addon's charts use (issue #405, epic #399). Books nothing.", "transport": "stdio", "runtime": "node", "entry": "budget-tools/server.mjs", "permissions": [ "addons/budget/reports" ], "toolPolicy": { "mode": "read-only", "allowDestructive": false }, "configRefs": [], "credentialRefs": [], "archiveEntry": "budget/mcp/servers/budget-tools/server.mjs", "sha256": "e4c8f779bb4dc1a7a813d6fbd2785cc3b15ba211c84679a9229c8d0e683e8c6a", "size": 27143, "descriptorVersion": 1 } ], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Per-User Budgeting: Konten, Kategorien, Budgets, wiederkehrende Transaktionen und
Charts (Ausgaben über Zeit, Kategorie-Aufschlüsselung, Budget vs Ist). Integriert
lesend mit den trading- + payments-Addons (realisierte PnL / bezahlte Rechnungen
fließen in die Reports), ohne diese zu verändern. Lokale SQLite ist die Quelle
der Wahrheit (ADR-054).
budget/addons/budgetKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials. Die
trading/payments-Integration ist optional und aktiviert sich automatisch, sobald
die Addons installiert sind.
budget_accounts — Konten (Name, Typ, Eröffnungsbilanz, Währung)budget_categories — Kategorien (Name, Gruppe)budget_budgets — Ausgabenlimits (Kategorie + Periode YYYY-MM, Betrag)budget_transactions — Einnahmen/Ausgaben (Konto, Kategorie, Betrag)budget_recurring — Wiederkehrende Regeln (Frequenz, Zeitraum, Betrag)Alle Tabellen sind per user_id scoped (ADR-054).
The higher-level brain that pursues configured business goals by running agent-driven **operator
cycles* which orchestrate the existing* money/business addons (dropshipping, seo-content, lead-gen,
wordpress) and the workflow-builder (#45) through the Aiopta API/gateway.
It drives those tools — it never re-implements them and never calls external services directly
(ADR-009). Every action is an Aiopta-internal /api/v1/addons/... call (same-origin guarded); planning goes
through the Aiopta gateway.
{ id, name, goal, target, status, mode, addons[], guardrails, agentId?, schedule? }.{ kpi?, target?, current? }.dry-run (default) | armed; status ∈ idle | running | paused.{ maxActionsPerCycle (≤10), maxActionsPerDay?, budgetCapCents? }.A cycle (POST …/operators/{id}/run) = gather state from the allow-listed addons → ask the
configured Aiopta agent for the next best action constrained to the allow-list → apply guardrails → record.
- Dry-run by default — a new operator only proposes; it runs NOTHING until explicitly armed.
- Per-operator allow-list — an action for an addon outside addons[] is refused, never run.
- Approval-required for side-effects — every spend / publish / outreach action is queued as a
pending action and is never auto-run, even when armed. Only a human approve carries it out — and
it still runs under the approver's RBAC + the target addon's own guardrails (e.g. lead-gen's anti-spam
confirm/suppression).
- Budget + per-day + per-cycle caps bound an armed operator.
- Same-origin only / no eval — assertSameOrigin re-checks every call; nothing is ever eval'd.
- Capability-gated — create/edit/arm/run/approve require the addon.manage RBAC capability.
Optionally, every newly-queued approval can ALSO be pushed through the notifications addon
(Discord/email/push/webhook) — in addition to the in-UI approvals inbox, never replacing it.
- Opt-in, default OFF. Per operator: notify = { enabled, channelId? }. Disabled/unconfigured ⇒
behaviour is unchanged (only the UI queue). When enabled, an optional channelId targets one channel;
omitted ⇒ broadcast to all enabled channels.
- Aiopta-API only (ADR-009). The bridge (src/lib/notify-bridge.ts) POSTs to the Aiopta-internal
POST /api/v1/addons/notifications/send (assertSameOrigin + a canonical-origin check, forwarded auth)
— it never calls Discord/email/an external host directly; the notifications addon owns the channel
credentials.
- Best-effort & idempotent. Fired once per pending action at queue time (not every cycle); a
notify failure never blocks/breaks the cycle and never weakens the approval gate (approval still
needs the human approve). The message carries the operator name, the action + risk, and a deep-link
to the approvals inbox. No secret/webhook URL is ever built or logged.
- UI. A "Freigaben auch per Benachrichtigung" toggle + channel picker in the operator editor.
Three addon-owned tables (created in install(), dropped in uninstall() via Aiopta core's getDb()):business_operator_operators, business_operator_runs, business_operator_pending_actions (the approval
queue). The addon never touches the core schema; no secret is stored.
A control panel: operator list, a per-operator editor (goal/KPI, allow-list checkboxes with per-action
risk, guardrails, Arm/Pause toggle, Run cycle), a plan/activity log, and a
pending-approvals inbox (approve/reject). The dry-run/armed state and approval gates are made visually
unmistakable.
Durable auto-scheduling of cycles and a fully-autonomous (no-approval) spend mode are parked owner/risk
decisions — see docs/OPEN-DECISIONS.md.
See SKILL.md for the agent-facing endpoint cheat-sheet anddocs/architecture/ADR-025-business-operator.md for the design.
Calendar UI and calendar integration API as an installable addon.
\ncalendarKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/calendar |
| GET | /api/v1/addons/calendar/status |
Manuell erstellte Kalender-Events sind pro Benutzer isoliert: sie liegen in der Tabellecalendar_events mit user_id NOT NULL und werden ausschließlich über scopedStore(auth.id) gelesen/
geschrieben (Owner server-seitig aus dem authentifizierten Aufrufer gestempelt, ein Client-Owner wird
ignoriert). Ein Benutzer sieht und erstellt nur seine eigenen Events. Die daneben angezeigten
Aufgaben- (project_tasks), Backup-Zeitplan- (backup_schedules) und verbundenen Kalender-Einträge
(integrations) sind schreibgeschützte Projektionen der Daten anderer Addons und werden hier nicht
neu partitioniert. Eine einmalige idempotente Migration hebt Alt-Events aus dem addon_settings-JSON-Blob
in die neue Tabelle (Owner = der Benutzer der Settings-Zeile).
Agent chat sessions, messages, streaming responses, chat agent selection — plus a
model-independent slash-command system, a full-width layout with a context sidebar, and in-app
deep-links (ADR-011, Phase U Block 4 / G10).
chat/chatKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\nEine Nachricht, die mit / beginnt, ist ein Command und kein Prompt. Commands werden
client-seitig abgefangen und ausgeführt — sie erreichen nie das Modell und funktionieren auch
dann, wenn kein Modell/Backend erreichbar ist (modellunabhängige Interception, ADR-011).
Beim Tippen von / öffnet sich ein Autocomplete-Popover (↑/↓ wählen, Enter/Tab übernehmen, Esc
schließen). Unbekannte /x-Eingaben zeigen einen Inline-Hinweis mit Vorschlägen — ebenfalls ohne
Modell-Aufruf.
| Command | Beschreibung | Offline |
|---|---|---|
| /help (/commands) | Alle Commands auflisten | ✅ |
| /model [provider/model] | Modell anzeigen / für die Session wechseln (Provider, Status, Fallbacks) | — |
| /skills [toggle <name>] | Skills des aktiven Agenten auflisten / (de)aktivieren | — |
| /mcp | MCP-Server & Tools auflisten | — |
| /tools | Für den Agent-Key freigegebene Tools/Endpunkte | — |
| /permissions (/perms) | Allow/Deny-Patterns des Agenten | — |
| /agent [name] | Aktiven Agenten anzeigen / (neue Session mit) Agent wechseln | ✅ |
| /system (/soul) | System-Prompt / Soul des Agenten anzeigen | — |
| /compact (/summarize) | Konversation zusammenfassen/komprimieren | — |
| /memory | Memory-Status anzeigen | — |
| /clear (/new, /reset) | Session zurücksetzen / neuen Chat | ✅ |
| /retry (/regenerate) | Letzte Nachricht erneut senden | ✅ |
| /stop (/abort, /cancel) | Laufende Antwort abbrechen | ✅ |
| /export | Chat als Markdown exportieren | ✅ |
Die Registry ist erweiterbar: registerSlashCommand(spec) inaddons/chat/src/lib/slash-commands.ts. Der Parser parseSlashCommand() ist rein und unit-getestet
(addons/chat/tests/unit/slash-commands.test.ts).
- Volle Breite: Die Nachrichtenspalte hat eine großzügige Lese-Maximalbreite, der Chat nutzt die
volle verfügbare Breite. Auf Desktop gibt es eine rechte Kontext-Sidebar (Agent,
Workspace-Status, Modell/Backend, Token/Kontext/Kosten, Quota, freigegebene Skills, laufende
Commands — DEVELOPMENT.md §7), auf Mobile ein Drawer.
- Deep-Links: Interne Links in Chat-/Fehler-/Empty-States öffnen keinen neuen Tab und laden
die App nicht neu, sondern springen über den Client-Router direkt zur Zielsektion (z. B.
/admin?section=providers). Helfer: addons/chat/src/lib/deep-links.ts.
| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/chat/agents |
| GET | /api/v1/addons/chat/plan-limits |
| GET, POST | /api/v1/addons/chat/sessions |
| DELETE | /api/v1/addons/chat/sessions/[id] |
| GET, POST | /api/v1/addons/chat/sessions/[id]/messages |
| POST | /api/v1/addons/chat/sessions/[id]/stream |
| POST | /api/v1/addons/chat/sessions/[id]/compact |
| GET, POST | /api/v1/addons/chat/groups |
| GET, POST | /api/v1/addons/chat/groups/[id]/members |
| DELETE | /api/v1/addons/chat/groups/[id]/members/[memberId] |
| GET, POST | /api/v1/addons/chat/groups/[id]/messages |
\nDie Core-Routen unter
/api/v1/chat/...sind dünne Proxies, die diese Addon-Handlerre-exportieren; die UI ruft die Core-Pfade auf.
Ein Gruppen-Chat ist eine Session mit einer Mitglieder-Liste: mehrereuser_ids + mehrere agent_ids teilen eine Konversation. Additiv zum 1:1-Chat — die
strikte 1:1-Isolation (#148 / ADR-054) bleibt unverändert.
- Datenmodell: neue Addon-Tabelle chat_session_members
(session_id, member_type user|agent, member_id, role owner|member, added_by).
Die Session bleibt im Besitz von user_sessions.user_id (dem Ersteller). Nachrichten
bleiben per session_id-FK an der Session — kein neues Owner-Feld pro Nachricht.
- Zugriff = Eigentümer ODER Nutzer-Mitglied (spiegelt das task-board-Muster exakt):
getAccessibleSession(userId, id) liefert die Session nur für Eigentümer oder ein
eingetragenes Nutzer-Mitglied; ein Nicht-Mitglied bekommt 404 (nicht 403, kein
Existenz-Leak, kein Admin-Bypass). Eine 1:1-Session hat keine Mitglieder-Zeilen,
daher reduziert sich getAccessibleSession dort auf den Eigentümer-Check
(getOwnedSession) — Gruppen können eine 1:1-Session nie aufweiten. Die bestehenden
sessions/[id]/*-Routen nutzen weiter getOwnedSession.
- @-Mention-Routing: In einer Gruppe antwortet ein Agent nur, wenn er per
@Name erwähnt wird (mehrere erwähnte Agenten antworten je einmal, in Roster-Reihenfolge).
Keine Erwähnung ⇒ kein Agent antwortet (verhindert N-Agenten-Sturm). Quoting für
Mehrwort-Namen: @"Ada Lovelace". Der mentionierte Agent wird wie heute über das Gateway
invoziert. Ein zwischenzeitlich entferntes Agent-Mitglied antwortet auch bei Erwähnung
nicht (Mitgliedschaft wird vor dem Senden erneut geprüft).
- Permission-gated: Nur der Eigentümer darf Mitglieder hinzufügen/entfernen
(Mitglied-aber-nicht-Eigentümer ⇒ 403, Fremder ⇒ 404). Einen Agenten einzuladen
erfordert, dass der Eigentümer diesen Agenten besitzt (cross-user Agent-ID
machtlos — derselbe Check wie createSession). Agent-Antworten respektieren die
Rechte-Obergrenze Eigentümer ∩ Agent (effectiveAgentCapabilities, ADR-055): der Agent
wurde vom Eigentümer eingeladen, der ihn besitzt, also ist seine Cap-Obergrenze durch den
Eigentümer begrenzt.
- Evil-User-Tests: addons/chat/tests/unit/group-chat-isolation.test.ts (reale
in-memory better-sqlite3, User A/B/C, Agenten/Gateway gemockt) + die reine
mentions.test.ts.
Chat-Sessions + Nachrichten sind strikt pro Nutzer isoliert. Die „Session" ist
die Core-Tabelle user_sessions (user_id NOT NULL); Nachrichten (chat_messages)
hängen per session_id-FK an der Session. Sämtlicher Zugriff läuft überaddons/chat/src/lib/chat-store.ts, das user_sessions über die Scope-Layer
(scopedStore/registerScopedTable) führt.
- Server-stamped Owner: Beim Anlegen wird user_id = auth.id gesetzt; ein vom
Client mitgeschickter Owner wird ignoriert. Eine Session kann nur an eigene
Agenten gebunden werden.
- 404 statt 403, kein Admin-Bypass: Jede sessions/[id]/*-Route
(route/messages/compact/stream) lädt die Session via getOwnedSession(auth.id, id).
Gehört sie einem anderen Nutzer (oder existiert nicht), kommt 404 zurück —
nicht der Inhalt, nicht 403, und auch ein Admin liest/streamt/komprimiert die
fremde Konversation nicht. Bei stream greift die 404 bevor der SSE-Stream
öffnet, bei messages/compact bevor irgendein Modell-Call passiert.
- gateway/LLM-Routing unberührt: Nur die Session/Message-Persistenz ist
isoliert; Streaming + Compaction bleiben für den Eigentümer voll funktional.
- agents ist auf die eigenen Agenten gescoped; plan-limits liest
instanzweite Provider-Limits (kein Per-User-Geheimnis).
Jede Chat-Nachricht läuft durch den echten Backend-Agent-Pfad
(hermes/openclaw) — niemals als roher Passthrough an ein LLM. Die Stream-Route
(sessions/[id]/stream/route.ts) ruft den Agenten-GatewaychatCompletionWithFallbacks(modelCandidates, opts, { backendId }) auf: Sie löst
die Modell-Fallback-Kette des Agenten auf (Primary zuerst), baut den SOUL-Prompt
und übergibt den Turn an den aktiven Backend-Driver. Selbst ohne explizit
aktiven Backend fällt das Gateway auf den verwalteten Default-Driver (openclaw)
zurück — ein Turn wird nie silent zu einem raw Provider-Call.
- Verifizierbare Evidenz pro Turn: addons/chat/src/lib/chat-agent-trace.ts
baut einen reinen Trace-Record (backend, agent, model, candidates, tools, via)
und schreibt eine grep-bare [chat:agent-path]-Zeile pro Turn ins Core-Log
(tail zeigt backend + agent + model + tools + via für jede Nachricht). Zusätzlich
emittiert die Route ein trace-SSE-Event mit demselben Record.
- via ist das Evidence-Flag: "backend" = der gebundene Backend-Driver
hat geantwortet (echter Backend-Agent); "provider" = ein explizit gewählter
roher Provider (aufgezeichnet, nicht silent); "fallback"/"unknown" = Degradation.
- UI-Transparenz: Der Chat-Header zeigt via <backend> · <model> · <via> · 🛠N
(Tools); der Standalone-Hook useChatStream exponiert activeBackend,
activeModel und agentPath.
- Per-User-Isolation unberührt: Der Trace trägt die userId des Eigentümers;
der gesamte Pfad bleibt durch getOwnedSession scope-gate-geschützt.
Tests: addons/chat/tests/unit/chat-agent-trace.test.ts (reine Trace-Shape- &
Log-Evidenz) + addons/chat/tests/unit/chat-agent-path.test.ts (Routing durch
den Agenten-Gateway mit Backend-Binding, Trace-Emission, Per-User-404).
- /compact ist modellabhängig (Zusammenfassung): bei nicht erreichbarem Modell kommt ein 503 und
der Command zeigt einen Hinweis.
- Der Markdown-Renderer ist absichtlich minimal (Code-Blöcke, Inline-Code, Fett/Kursiv, Listen,
Links); kein vollständiger Markdown-Parser.
Aiopta addon wrapper for the ComfyUI Web App with embedded UI, connection config, and passthrough API endpoints.
\ncomfyui-web-app/addons/comfyui-web-appKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/comfyui-web-app/config |
| POST | /api/v1/addons/comfyui-web-app/execute |
| GET | /api/v1/addons/comfyui-web-app/jobs |
| GET | /api/v1/addons/comfyui-web-app/status |
| GET | /api/v1/addons/comfyui-web-app/workflows |
", "byteSize": 951 } } }, { "id": "commerce", "uuid": "5ba1c6f2-d305-4007-a736-3e5d6595ef70", "name": "Commerce", "version": "0.6.3", "description": "Commerce consolidation hub (Slices 2–5): the canonical connector framework + shared Order/Inventory model that the channel addons migrate into. Shopify (Slice 2, #588), Etsy (Slice 3, #589), Dropshipping/POD (Slice 4, #590) and Marketplace-Automation (Slice 5, #591) are integrated as connectors. Each connector is per-user BYOK (ADR-054) with its own credentials; sync/fulfillment is always an explicit call. External SaaS APIs — no container.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "commerce", "commerce-connector-framework", "commerce-connectors", "commerce-sync", "commerce-shopify", "commerce-etsy", "commerce-dropshipping", "commerce-dropshipping-margins", "commerce-pod-printful", "commerce-pod-printify", "commerce-marketplace", "commerce-marketplace-accounts", "commerce-marketplace-listings", "commerce-marketplace-publish" ], "tags": [], "download": "/artifacts/commerce-0.6.3.zip", "sha256": "f05534b28562d9ddb761333101f40cdf24a79b9bbb98c2be3aeeccf01b766463", "size": 392340, "page": { "id": "commerce-page", "path": "/addons/commerce", "name": "Commerce", "icon": "🛒", "section": "Money", "component": "@addons/commerce/src/page" }, "deprecated": false, "endpoints": [ "/api/v1/addons/commerce/status", "/api/v1/addons/commerce/connectors", "/api/v1/addons/commerce/shopify/status", "/api/v1/addons/commerce/shopify/config", "/api/v1/addons/commerce/shopify/products", "/api/v1/addons/commerce/shopify/stock", "/api/v1/addons/commerce/shopify/orders", "/api/v1/addons/commerce/shopify/sync", "/api/v1/addons/commerce/etsy/status", "/api/v1/addons/commerce/etsy/config", "/api/v1/addons/commerce/etsy/products", "/api/v1/addons/commerce/etsy/stock", "/api/v1/addons/commerce/etsy/orders", "/api/v1/addons/commerce/etsy/sync", "/api/v1/addons/commerce/dropshipping/status", "/api/v1/addons/commerce/dropshipping/config", "/api/v1/addons/commerce/dropshipping/products", "/api/v1/addons/commerce/dropshipping/orders", "/api/v1/addons/commerce/dropshipping/orders/:id", "/api/v1/addons/commerce/dropshipping/orders/:id/fulfill", "/api/v1/addons/commerce/dropshipping/fulfillments", "/api/v1/addons/commerce/dropshipping/margins", "/api/v1/addons/commerce/dropshipping/sync", "/api/v1/addons/commerce/marketplace/status", "/api/v1/addons/commerce/marketplace/accounts", "/api/v1/addons/commerce/marketplace/accounts/:id", "/api/v1/addons/commerce/marketplace/listings", "/api/v1/addons/commerce/marketplace/listings/:id", "/api/v1/addons/commerce/marketplace/listings/:id/publish", "/api/v1/addons/commerce/marketplace/jobs" ], "skills": [ { "name": "commerce-status", "displayName": "Commerce: Connector overview", "description": "List the registered commerce connectors and which the caller has configured (BYOK).", "permissions": [ "addons/commerce/read" ], "endpoint": "/api/v1/addons/commerce/status", "scripts": [] }, { "name": "commerce-shopify-sync", "displayName": "Commerce/Shopify: Sync products / stock / orders", "description": "Trigger an explicit sync of the caller's Shopify shop (products, stock and orders) via the Admin API using the user's BYOK access token. Migrated from standalone shopify addon (Slice 2, #588).", "permissions": [ "addons/commerce/shopify/sync", "addons/commerce/shopify/products", "addons/commerce/shopify/orders" ], "endpoint": "/api/v1/addons/commerce/shopify/sync", "scripts": [] }, { "name": "commerce-shopify-products", "displayName": "Commerce/Shopify: Products & Stock", "description": "List the caller's cached Shopify products and stock levels, or write back a stock level to Shopify. Migrated from standalone shopify addon (Slice 2, #588).", "permissions": [ "addons/commerce/shopify/products", "addons/commerce/shopify/stock" ], "endpoint": "/api/v1/addons/commerce/shopify/products", "scripts": [] }, { "name": "commerce-shopify-orders", "displayName": "Commerce/Shopify: Orders", "description": "List the caller's cached Shopify orders. Migrated from standalone shopify addon (Slice 2, #588).", "permissions": [ "addons/commerce/shopify/orders" ], "endpoint": "/api/v1/addons/commerce/shopify/orders", "scripts": [] }, { "name": "commerce-etsy-sync", "displayName": "Commerce/Etsy: Sync listings / stock / orders", "description": "Trigger an explicit sync of the caller's Etsy shop (listings, stock and orders/receipts) via the OpenAPI v3 API. Migrated from standalone etsy addon (Slice 3, #589).", "permissions": [ "addons/commerce/etsy/sync", "addons/commerce/etsy/products", "addons/commerce/etsy/orders" ], "endpoint": "/api/v1/addons/commerce/etsy/sync", "scripts": [] }, { "name": "commerce-etsy-products", "displayName": "Commerce/Etsy: Listings & Stock", "description": "List the caller's cached Etsy listings and stock levels, or write back a stock level to Etsy. Migrated from standalone etsy addon (Slice 3, #589).", "permissions": [ "addons/commerce/etsy/products", "addons/commerce/etsy/stock" ], "endpoint": "/api/v1/addons/commerce/etsy/products", "scripts": [] }, { "name": "commerce-etsy-orders", "displayName": "Commerce/Etsy: Orders", "description": "List the caller's cached Etsy orders/receipts. Migrated from standalone etsy addon (Slice 3, #589).", "permissions": [ "addons/commerce/etsy/orders" ], "endpoint": "/api/v1/addons/commerce/etsy/orders", "scripts": [] }, { "name": "commerce-dropshipping-catalog", "displayName": "Commerce/Dropshipping: Catalog & Import", "description": "List Printful/Printify catalog products (with margin-applied retail prices) and import one into the shop. Migrated from standalone dropshipping addon (Slice 4, #590).", "permissions": [ "addons/commerce/dropshipping/products", "addons/commerce/dropshipping/status" ], "endpoint": "/api/v1/addons/commerce/dropshipping/products", "scripts": [] }, { "name": "commerce-dropshipping-orders", "displayName": "Commerce/Dropshipping: Orders & Fulfillment", "description": "List/create draft orders and explicitly fulfill them (forward to the supplier for production). Fulfillment moves money and is never implicit. Migrated from standalone dropshipping addon (Slice 4, #590).", "permissions": [ "addons/commerce/dropshipping/orders", "addons/commerce/dropshipping/fulfillment" ], "endpoint": "/api/v1/addons/commerce/dropshipping/orders", "scripts": [] }, { "name": "commerce-dropshipping-margins", "displayName": "Commerce/Dropshipping: Margin Rules", "description": "Read or set per-user margin rules (percent + fixed, charm-rounding) that turn supplier base cost into retail price. Migrated from standalone dropshipping addon (Slice 4, #590).", "permissions": [ "addons/commerce/dropshipping/margins" ], "endpoint": "/api/v1/addons/commerce/dropshipping/margins", "scripts": [] }, { "name": "commerce-marketplace-accounts", "displayName": "Commerce/Marketplace: Accounts", "description": "List, create, update and delete the caller's connected marketplace accounts (Kleinanzeigen, eBay, Vinted). Migrated from standalone marketplace-automation addon (Slice 5, #591).", "permissions": [ "addons/commerce/marketplace/accounts" ], "endpoint": "/api/v1/addons/commerce/marketplace/accounts", "scripts": [] }, { "name": "commerce-marketplace-listings", "displayName": "Commerce/Marketplace: Listings", "description": "List, create and update listing drafts for marketplace publication. Migrated from standalone marketplace-automation addon (Slice 5, #591).", "permissions": [ "addons/commerce/marketplace/listings" ], "endpoint": "/api/v1/addons/commerce/marketplace/listings", "scripts": [] }, { "name": "commerce-marketplace-publish", "displayName": "Commerce/Marketplace: Publish & Jobs", "description": "Trigger an explicit publish of a listing to its target providers and track publish jobs. Publish is always an explicit call (ADR-013). Migrated from standalone marketplace-automation addon (Slice 5, #591).", "permissions": [ "addons/commerce/marketplace/publish", "addons/commerce/marketplace/jobs" ], "endpoint": "/api/v1/addons/commerce/marketplace/jobs", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": null }, { "id": "container-orchestrator", "uuid": "d4e8ceba-d31e-4b2f-aa0b-f7ae3f23b557", "name": "Container Orchestrator (Lifecycle + Resource Limits + Health + Ephemeral Leases + Prometheus Metrics)", "version": "0.8.5", "description": "Aiopta Container Orchestrator — slices 1+2+3+4 of issues #354/#355/#356/#357. Slice 1/4 establishes the public API schema (ContainerRequest, ContainerStatus, ContainerAction), the pure-function action handlers (start/stop/restart with drift protection + state-transition matrix), and the request-shape validator. Slice 2/4 wires the docker-manager adapter behind the same seam (fake adapter for tests, real adapter behind feature flag) and adds the scoped operation store, drift detection, audit log, and preview. Slice 3/4 adds resource-limits (CPU/RAM/PIDs/Disk) + health monitoring (HTTP/TCP/exec probes) + cursor-paginated metrics + integration glue. Slice 4/4 adds the ephemeral-agent-container surface: lease-model + GC + crash-recovery + idempotent renew/release. Cross-user lookups map to 404 (no enumeration leak). The orchestrator does NOT expose delete/prune/exec/image-pull — those remain in the underlying docker-manager addon.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "container-lifecycle", "container-start", "container-stop", "container-restart", "container-status", "container-pure-handler", "container-request-validation", "container-drift-protection", "container-state-transition-matrix", "container-noop-on-redundant", "container-secret-shape-rejection", "container-log-injection-guard", "container-destroy", "container-state-machine", "container-drift-detection", "container-idempotency", "container-audit", "container-health-probe-stub", "fake-adapter-seam", "container-resource-limits", "container-resource-limits-validation", "container-resource-limits-host-capacity-check", "container-resource-limits-idempotent", "container-health-probe", "container-health-probe-http", "container-health-probe-tcp", "container-health-probe-exec", "container-health-probe-timeout", "container-health-probe-job-cancellation", "container-health-event-log", "container-health-event-severity-warning", "container-metrics-aggregation", "container-metrics-cursor-pagination", "container-metrics-user-isolation", "container-ephemeral-create", "container-ephemeral-renew", "container-ephemeral-release", "container-ephemeral-lease-model", "container-ephemeral-lease-gc", "container-ephemeral-crash-recovery", "container-ephemeral-default-quotas", "container-ephemeral-idempotent-replay", "container-ephemeral-per-user-isolation", "container-resource-sample", "container-resource-sample-quota-relative", "container-resource-sample-cursor-pagination", "container-prometheus-metrics-export", "container-prometheus-metrics-label-scoping", "container-prometheus-metrics-per-user-isolation", "container-standard-dashboard" ], "tags": [], "download": "/artifacts/container-orchestrator-0.8.5.zip", "sha256": "1f970ce33d73d976f77cfdff9d64b199e3457bf4a98cefb272591f38e8a9927e", "size": 587208, "page": null, "deprecated": false, "endpoints": [ "/api/v1/addons/container-orchestrator/health", "/api/v1/addons/container-orchestrator/containers/:id/status", "/api/v1/addons/container-orchestrator/containers/:id/preview", "/api/v1/addons/container-orchestrator/containers/:id/start", "/api/v1/addons/container-orchestrator/containers/:id/stop", "/api/v1/addons/container-orchestrator/containers/:id/restart", "/api/v1/addons/container-orchestrator/containers/:id/resource-limits", "/api/v1/addons/container-orchestrator/containers/:id/health", "/api/v1/addons/container-orchestrator/containers/:id/metrics", "/api/v1/addons/container-orchestrator/metrics", "/api/v1/addons/container-orchestrator/containers/:id/resource-samples", "/api/v1/addons/container-orchestrator/ephemeral", "/api/v1/addons/container-orchestrator/ephemeral/lease", "/api/v1/addons/container-orchestrator/ephemeral/release" ], "skills": [ { "name": "container-orchestrator-view", "displayName": "Container Orchestrator: Container-Status lesen", "description": "Liest den aktuellen Lifecycle-State eines Containers (running | stopped | restarting | exited | paused | unknown). Read-only, idempotent.", "permissions": [ "addons/container-orchestrator/containers/status" ], "endpoint": "/api/v1/addons/container-orchestrator/containers/:id/status", "scripts": [] }, { "name": "container-orchestrator-manage", "displayName": "Container Orchestrator: Container-Actions (start/stop/restart)", "description": "Wendet start | stop | restart auf einen Container an. Drift-Schutz via snapshotHash, idempotencyKey erforderlich, explizite noop/drift/timeout/rejected Results. Audit-Log ohne Secrets.", "permissions": [ "addons/container-orchestrator/containers/start", "addons/container-orchestrator/containers/stop", "addons/container-orchestrator/containers/restart" ], "endpoint": "/api/v1/addons/container-orchestrator/containers/:id/start", "scripts": [] }, { "name": "container-orchestrator-resource-limits", "displayName": "Container Orchestrator: Resource-Limits setzen", "description": "Setzt CPU/RAM/PIDs/Disk-Quotas für einen Container. Validiert gegen Host-Kapazität, idempotent (zweiter Aufruf mit gleichem Payload ist noop). QUOTA_EXCEEDS_HOST → 400. Slice 3/4 von #356.", "permissions": [ "addons/container-orchestrator/containers/resource-limits" ], "endpoint": "/api/v1/addons/container-orchestrator/containers/:id/resource-limits", "scripts": [] }, { "name": "container-orchestrator-health", "displayName": "Container Orchestrator: Health-Probe", "description": "Führt eine einzelne Health-Probe (HTTP/TCP/exec) gegen einen Container aus. Status healthy | unhealthy | unknown, Latenz in ms. Slice 3/4 von #356.", "permissions": [ "addons/container-orchestrator/containers/health" ], "endpoint": "/api/v1/addons/container-orchestrator/containers/:id/health", "scripts": [ { "id": "container-orchestrator-health-cli", "name": "container-orchestrator-health-cli", "path": "container-orchestrator-health/cli.sh", "sha256": "11f51a07d8253c8c52b63c79273ef051846210f6aaa011919bde774ff5c57703", "interpreter": "bash", "timeoutMs": 10000, "permissions": [ "addons/container-orchestrator/containers/health" ], "inputSchema": { "type": "object", "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "timeoutMs": { "type": "integer", "minimum": 100, "maximum": 300000 }, "id": { "type": "string", "pattern": "^[A-Za-z0-9._-]+$", "description": "Resource-Id — ersetzt :id im Endpoint" } }, "required": [ "id" ] }, "outputSchema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "integer" }, "data": {}, "error": { "type": "string" }, "truncated": { "type": "boolean" } } }, "size": 12248 } ] }, { "name": "container-orchestrator-metrics", "displayName": "Container Orchestrator: Health-Metriken", "description": "Cursor-paginierte Health-Samples pro Container (default limit=20, max=100), inkl. successRate + p50/p95 Latency. Pro-User isoliert. Slice 3/4 von #356.", "permissions": [ "addons/container-orchestrator/containers/metrics" ], "endpoint": "/api/v1/addons/container-orchestrator/containers/:id/metrics", "scripts": [] }, { "name": "container-orchestrator-resource-samples", "displayName": "Container Orchestrator: Resource-Samples (CPU/RAM/Netz/IO)", "description": "Cursor-paginierte ResourceSample-Rows pro Container (CPU/RAM/Netz/IO, default limit=20, max=100), quota-relativiert gegen memoryLimitBytes (ADR-CO-07). Pro-User isoliert. ADR-CO-06 (#573).", "permissions": [ "addons/container-orchestrator/containers/resource-samples" ], "endpoint": "/api/v1/addons/container-orchestrator/containers/:id/resource-samples", "scripts": [] }, { "name": "container-orchestrator-prometheus-metrics", "displayName": "Container Orchestrator: Prometheus /metrics Export", "description": "Pull-basierter Prometheus-Textformat-Export (/metrics) über Health- + Resource-Samples. container_id-Label immer, owner-Label nur für Admin (per-User gefiltert, Isolation erhalten). ADR-CO-06 Option D (#573).", "permissions": [ "addons/container-orchestrator/metrics" ], "endpoint": "/api/v1/addons/container-orchestrator/metrics", "scripts": [] }, { "name": "container-orchestrator-ephemeral-create", "displayName": "Container Orchestrator: Ephemeral-Container erstellen (lease-modell)", "description": "Erstellt einen ephemeren Container mit definiertem Lease (TTL 1..86400s). Container wird automatisch gestoppt nach Lease-Ablauf, GC sweep alle 60s. Idempotent auf leaseKey. Slice 4/4 von #357.", "permissions": [ "addons/container-orchestrator/ephemeral" ], "endpoint": "/api/v1/addons/container-orchestrator/ephemeral", "scripts": [] }, { "name": "container-orchestrator-ephemeral-renew", "displayName": "Container Orchestrator: Ephemeral-Lease erneuern", "description": "Verlängert das Lease eines ephemeren Containers um leaseTtlSeconds (absolut, nicht additiv). Idempotent: gleicher leaseKey mit gleichem TTL gibt dieselbe Response ohne doppelte Verlängerung. Slice 4/4 von #357.", "permissions": [ "addons/container-orchestrator/ephemeral/lease" ], "endpoint": "/api/v1/addons/container-orchestrator/ephemeral/lease", "scripts": [] }, { "name": "container-orchestrator-ephemeral-release", "displayName": "Container Orchestrator: Ephemeral-Container explizit freigeben", "description": "Setzt Lease-Status auf `released` und stoppt den Container sofort. Idempotent: replay nach erfolgreichem Release gibt noop zurück. Slice 4/4 von #357.", "permissions": [ "addons/container-orchestrator/ephemeral/release" ], "endpoint": "/api/v1/addons/container-orchestrator/ephemeral/release", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Container lifecycle management for the Aiopta platform. Slice 2 ships the
start / stop / restart / destroy mutating surface with idempotent
semantics, drift detection, scoped operation store, and an audit log.
Die offenen Architektur-/Produktentscheidungen der Container-Orchestrator-API
(Epic #207, gesammelte Owner-Runde #390) sind als ADR-Vorlagen (Kontext,
Optionen mit Trade-offs, begründete Empfehlung) indocs/adr/ dokumentiert (Serie ADR-CO-01 … ADR-CO-08,
Status Proposed — Owner-Entscheidung ausstehend).
| # | Slice | Status |
|---|---|---|
| 1 | Manifest schema (slice #354) | prerequisite |
| 2 | Container lifecycle (this slice) | ✅ |
| 3 | Health probes + resource quotas | upcoming |
| 4 | Ephemeral agent containers | upcoming |
The slice is a bounded context. It does NOT import from docker-manager
or development — the patterns from those addons are mirrored
shape-for-shape but kept independent (see issue #355 Architektur-Vorgabe:
"Pattern, kein Import").
src/lib/\n├── types.ts Domain types (Container, ContainerState, ...)\n├── state-machine.ts Pure transition table (start|stop|restart|destroy)\n├── store.ts In-memory scoped container registry\n├── adapter.ts FakeContainerAdapter (deterministic, hermetic)\n├── operation-store.ts Idempotency-key store (7-day TTL)\n├── drift.ts Snapshot hash + drift detection + user-scope guard\n├── preview.ts Preview pipeline + dispatch-log audit\n├── handlers.ts runStart / runStop / runRestart / runDestroy\n├── health.ts Addon-level health probe (slice-3 will add per-container)\n└── manifest.ts Public export surface| AC | Test |
|---|---|
| container_stop on stopped → 200 idempotentReplay (no double-persist) | tests/unit/idempotency.test.ts |
| Cross-user → 404 (no enumeration leak) | tests/unit/user-isolation.test.ts |
| Drift detected → 409 DRIFT_DETECTED | tests/unit/drift.test.ts, tests/unit/stop.test.ts |
| Adapter timeout > 30s → pending, retry re-attaches | tests/unit/timeout.test.ts |
| Container orphan during operation → state: orphaned | tests/unit/orphan-recovery.test.ts |
| restart on exited is equivalent to start | tests/unit/restart.test.ts |
| start on running → 200 idempotentReplay | tests/unit/start.test.ts |
| 7-day retention (no auto-delete < 7d) | tests/unit/operation-store.test.ts |
| Audit log with latencyMs | tests/unit/audit.test.ts |
| State machine correctness (32 transitions) | tests/unit/state-machine.test.ts |
npm test59 unit tests across 11 suites. All passing as of slice 2/4.
\nnode >= 20 (uses node --experimental-strip-types for tests).crypto (built-in) for snapshot hashing.RemoteAgentAdapter) — lands with parent #39.The flagship admin/setup copilot: an agent that controls, manages, sets up and configures Aiopta
itself via natural language — available right after onboarding (the core of the "2-minute
aha"). It drives the platform's own management operations through the agent-capable
Live-OpenAPI (ADR-022); there is no container — it reuses the platform's own agent/backend
infrastructure (connector/internal pattern, ADR-009).
This is powerful and dangerous, so the security model is the most important part.
\n- Diagnose (read-only): read health/status, list configured providers + the active backend, list
addons + agents, and surface problems with proposed fixes.
- Config: get/set settings (public URL, mail, connections), set/rotate LLM/provider keys, select the
active backend.
- Addons: list, enable/disable, configure.
- Agents: list, create, edit, delete.
- Build: create a dashboard/widget, create a workflow (via the workflow-builder).
Each tool wraps an existing platform-API endpoint — the copilot never re-implements core and never
calls an external service.
- mc.manage capability, default-deny. Every management tool is gated by the owner/admin-only
mc.manage RBAC capability (ADR-005, Phase S). A plain user — and a normal user-scoped agent key
(which resolves to role user) — is denied 403 with no side effect. The route enforces it via
requireCapability(request, "mc.manage"), and the engine re-asserts hasCapability (defence in depth).
- Sensitive ⇒ approval, never direct. Delete / grant-root / move-money / external-post / secret-
rotate / addon-enable are never executed directly — they are queued as a pending action and run
ONLY after a human approves (delivered to the approvals panel + optionally a notification). Read/diagnose
+ reversible config run directly.
- Audited + masked. Every tool invocation writes a logAudit row (actor, action, target, params);
secret-bearing fields are masked — a secret value is never logged in clear.
- Same-origin only. Every tool path is a literal /api/v1/... path, re-checked at request time —
the copilot can never reach an external host. The owner's auth is forwarded to each internal call so
platform RBAC re-applies server-side.
- Agent-key scoping (S1). The copilot's own agent key is provisioned least-privilege; it does not by
itself carry mc.manage. The copilot acts on the owner's forwarded auth — the audited trust
boundary — so an out-of-scope or capabilityless caller is denied.
Reuses the existing approval+notify mechanism established by business-operator (ADR-025) and the
notifications-approval delivery (C7 / ADR-035). A sensitive action creates a pending row the owner
confirms in the console's Freigaben panel (and optionally via the notifications addon). On approval
the action runs (and is audited as copilot.action.approved); on rejection it is dropped (audited ascopilot.action.rejected).
- Page /addons/copilot — the Aiopta Copilot console (chat + quick-action
suggestions + a tool catalog with approval gates + the approvals panel). Renders a graceful
"connect a backend / seed the copilot" state when not configured.
- Widget copilot.ask — "Frag Aiopta": a prompt box that opens the console with the
question prefilled, plus readiness + open-approval count.
seedCopilotAgent(owner) (in src/lib/seed.ts) provisions the copilot as an idempotent
system-agent (soul, model from the active backend, the management skills) via the sharedprovisionAgentFromSpec. The onboarding-completion hook (#96) calls it at onboarding end; an admin can
also seed it now via POST /api/v1/addons/copilot/seed.
The conversation turn runs through gatewayChatCompletion with { needsTools: true } (ADR-038): when
the active backend supports native tool-calling it runs there, otherwise the gateway falls back to the
default path. Memory/Tools/Orchestration are reused via the gateway, never reimplemented.
See ADR-040 and SKILL.md for the full contract.
Vollständiges CRM auf der lead-gen-CRM-lite (ADR-015): Firmen (Organisationen), Kontakte (Personen, optional einer Firma zugeordnet), eine Deal-Pipeline (Stages → Deals), Aktivitäten (Anrufe/Notizen/Aufgaben/Meetings, an Kontakte/Deals gehängt) und eine E-Mail-/Touchpoint-Timeline. Lokale SQLite ist die Quelle der Wahrheit; reine Daten — KEIN externer Container, KEIN Provider, KEIN Secret. Jede Zeile ist pro Nutzer isoliert (user_id, ADR-054): Nutzer B sieht/ändert nie die Daten von Nutzer A. Ein erfasster lead-gen-Lead kann per Import zu einem CRM-Kontakt werden (lose Verknüpfung über die E-Mail, kein Hard-Coupling). ADR-054.
\ncrm ist das kanonische Ziel-Addon der CRM-Konsolidierung. Das lead-gen-Addon (Lead-Capture +
Cold Outreach) ist als deprecated markiert (replacedBy: crm, Sunset 2026-12-31) und wird
hierher zusammengeführt. Die gewählte Umsetzung ist datenerhaltend und rückwärtskompatibel:
- Ein Ziel-Addon: crm ist die durable Relationship-Ebene, auf der lead-gen laut ADR-015 ohnehin
aufsetzt. lead-gens Fähigkeiten bleiben im Alias-Fenster erreichbar; die Nachfolge zeigt auf crm.
- Verlustfreie Migration: die per-Nutzer-Brücke POST /api/v1/addons/crm/import/leads
(importLeads) liest lead-gens eigenen, bereits nutzer-isolierten Store und legt jeden Lead als
CRM-Kontakt an (idempotent, per E-Mail verknüpft, leadEmail-Rückreferenz). Es wird **keine Zeile
kopiert oder gelöscht** — die lead_gen_*-Tabellen bleiben unverändert bestehen (loss-free „by
construction“, analog zum Core-Boot-Reconcile).
- Alt-ID-Redirect: auf Addon-Ebene über lead-gens Metadaten (replacedBy: crm, sunset,
settingsPagePath: /addons/crm) — Marketplace/Settings-Hub zeigen den Nachfolger; auf
Datensatz-Ebene löst der kanonische Resolver getContactByLeadEmail(userId, email)
(src/lib/lead-redirect.ts) eine alte lead-gen-Lead-Identität (per E-Mail) auf den migrierten
CRM-Kontakt auf.
- Bewusst NICHT (Owner-Entscheidung): das schwere Outreach-Maschinenwerk (Scraper-Container,
AI-Sequenzen, garantierter Versand, Suppression) wird nicht in einem Schritt physisch nach crm
verschoben — das würde eine riskante Zusammenführung zweier unterschiedlicher Kontakt-/Pipeline-
Datenmodelle bedeuten. lead-gens Routen bleiben unverändert (deprecated, aber funktional); die
Code-Relocation zu reinen Re-Export-Shims samt HTTP-Redirect-Headern ist der Folge-Schritt vor dem
Entfernen (ADR-008 „one PR per cluster“).
- Lizenz: beide Addons sind UNLICENSED/first-party (author Aiopta); die Konsolidierung ändert
keine Drittlizenz. Keine neue Abhängigkeit.
- Pricing: lead-gen ist „Money-Stufe-1“; crm ist reine Daten ohne Container/Secret. Es wird **kein
neuer bezahlter Flow** eingeführt. Der garantierte E-Mail-Versand (der einzige kostenwirksame Pfad)
bleibt im deprecated lead-gen hinter seinen Guardrails; crm selbst versendet nichts.
- Permissions: crm bleibt least-privilege und rein nutzer-isoliert (ADR-054, jede Zeile
user_id-gestempelt). Die Brücke liest ausschließlich die eigenen lead-gen-Daten des Aufrufers
über dessen bereits gescopten Store — kein Cross-User-Zugriff, keine neue Berechtigung. lead-gens
Skills (inkl. des separaten Sende-Skills) bleiben unverändert.
crm/addons/crmcrm.summaryKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/crm/activities |
| GET, PUT, DELETE | /api/v1/addons/crm/activities/[id] |
| GET, POST | /api/v1/addons/crm/companies |
| GET, PUT, DELETE | /api/v1/addons/crm/companies/[id] |
| GET, POST | /api/v1/addons/crm/contacts |
| GET, PUT, DELETE | /api/v1/addons/crm/contacts/[id] |
| GET | /api/v1/addons/crm/contacts/[id]/detail |
| GET, POST | /api/v1/addons/crm/contacts/[id]/touchpoints |
| GET, POST | /api/v1/addons/crm/deals |
| GET, PUT, DELETE | /api/v1/addons/crm/deals/[id] |
| PUT | /api/v1/addons/crm/deals/[id]/stage |
| POST | /api/v1/addons/crm/import/leads |
| GET | /api/v1/addons/crm/status |
| GET | /api/v1/addons/crm/widget |
", "byteSize": 4882 } } }, { "id": "cubee3d-hive", "uuid": "3ebf6c8a-6232-4d6b-b6bc-9fb4b41bf0a2", "name": "Cubee3D Hive", "version": "1.1.2", "description": "Cubee3D Hive catalog reader — lists catalogs, products and 3D-designer assets from the Wix-hosted storefront using an authenticated session or BYOK API key. Automated Wix credential login remains separately tracked until Cubee3D provides a stable supported contract. Requires the WordPress & WooCommerce addon for downstream product sync.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "3d-products", "hive-catalog" ], "tags": [], "download": "/artifacts/cubee3d-hive-1.1.2.zip", "sha256": "622662bc07a7d16ffa7a6bcb5dae17a0d210cf28020e9b11994e888242b96a41", "size": 133124, "page": { "id": "cubee3d-hive-page", "path": "/addons/cubee3d-hive", "name": "Cubee3D Hive", "icon": "🎲", "section": "Tools", "component": "@addons/cubee3d-hive/src/page" }, "deprecated": false, "endpoints": [ "/api/v1/addons/cubee3d-hive/catalogs", "/api/v1/addons/cubee3d-hive/products", "/api/v1/addons/cubee3d-hive/credentials" ], "skills": [], "mcpServers": [ { "id": "cubeehive-tools", "displayName": "Cubee3D Hive tools", "description": "Read-only Cubee3D/Hive catalog tools for agents: list catalogs, list products, get a single product. Read-only — no sync/mutation tools (those stay in the addon's authenticated write API).", "transport": "stdio", "runtime": "node", "entry": "cubeehive-tools/server.mjs", "permissions": [ "addons/cubee3d-hive/read" ], "toolPolicy": { "mode": "read-only", "allowDestructive": false }, "archiveEntry": "cubee3d-hive/mcp/servers/cubeehive-tools/server.mjs", "sha256": "5d53de6517b5676094a698efce633b08a844e5a410cf5e2a9ba6501e559bcd32", "size": 12085, "descriptorVersion": 1 } ], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Cubee3D Hive Katalog-Leser — listet Kataloge, Produkte und 3D-Designer-Assets
des Wix-gehosteten Storefronts, über eine authentifizierte Session oder BYOK
API-Key. Nur lesend; für den Downstream-Produkt-Sync wird das WordPress- &
WooCommerce-Addon benötigt.
cubee3d-hive/addons/cubee3d-hivewordpress >= 1.2.0 (Downstream-Produkt-Sync)BYOK: im Frontend oder via POST /credentials einen API-Key hinterlegen
(mode: apiKey) bzw. eine authentifizierte Wix-Session (mode: cookies). Der
Credential-Status ist per-User gescoped; die Werte selbst werden nie in
Antworten gespiegelt, nicht einmal maskiert (#1056 S1) — GET /credentials
liefert nur { configured, mode }.
| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/cubee3d-hive/catalogs |
| GET | /api/v1/addons/cubee3d-hive/products |
| GET, POST | /api/v1/addons/cubee3d-hive/credentials |
- Reiner Katalog-Leser (Slice 1): Schreib-Operationen auf den Storefront
sind nicht Teil des Addons.
- Automatisierter Wix-Credential-Login bleibt separat getrackt, bis Cubee3D
einen stabilen unterstützten Vertrag liefert.
", "byteSize": 1417 } } }, { "id": "dataannotation-bot", "uuid": "303118cb-e901-4b42-9f80-29e7ae9df28f", "name": "DataAnnotation Bot", "version": "1.0.2", "description": "Human-like task automation for DataAnnotation.tech — browser automation (Puppeteer), Bezier-curve mouse movements, scheduling, and reporting. Runs as a Aiopta extension.", "author": "Aiopta", "icon": "🤖", "capabilities": [ "automation", "browser", "puppeteer", "scheduling", "human-like-input" ], "tags": [], "download": "/artifacts/dataannotation-bot-1.0.2.zip", "sha256": "b09f1ddd547b701f2c6205683a9f9ad041026093533e707de700faeae7250b18", "size": 54321, "page": null, "deprecated": false, "endpoints": [ "/api/dataannotation-bot/status" ], "skills": [], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README manuell gepflegt (addon.json + Routen als Quelle).
Human-like task automation for DataAnnotation.tech, built as an Aiopta extension.
\n### 🖱️ Browser Automation (Puppeteer)
- Full headless/headed browser control via Puppeteer
- Realistic viewport (1920×1080) and user agent
- Anti-detection: removes navigator.webdriver, fakes plugins/languages
- Disables AutomationControlled Chrome feature
### 🎯 Human-like Mouse Movements (Bezier Curves)
- Quadratic Bezier curves with random control points for natural cursor paths
- Eased interpolation — slower at start/end, faster in middle (mimics real hand acceleration)
- Micro-jitter — ±1-2px random offset on each step for realism
- Variable step count based on distance (more steps for longer moves)
- Pre/post-click pauses (100-300ms and 50-150ms)
- Hover dwell time — random 200-800ms hover before action
### ⌨️ Human-like Typing
- Variable keystroke delay (50-200ms per character)
- 3% typo rate — occasional double-char with backspace correction
- Natural backspace timing (100-300ms)
### 📅 Human Scheduling
- Weekday evenings: 19:00–23:00
- Early mornings: 06:00–08:00
- Weekends: 10:00–22:00
- Never during business hours (9-17 weekdays)
- 15% random day-off chance
### 📊 Reporting
- Session logging (tasks, earnings, duration)
- Daily reports with effective hourly rate
- 7-day rolling history
addons/dataannotation-bot/\n├── src/\n│ ├── index.ts # Addon registration\n│ ├── bot/\n│ │ ├── human-bot.ts # Main bot orchestrator\n│ │ ├── browser-automation.ts # Puppeteer wrapper\n│ │ ├── mouse-movements.ts # Bezier curve mouse simulation\n│ │ ├── schedule.ts # Work-hour scheduler\n│ │ └── report.ts # Session reporting\n│ ├── api/\n│ │ ├── bot-status.route.ts # GET /api/dataannotation-bot/status\n│ │ ├── bot-control.route.ts # POST /api/dataannotation-bot/control\n│ │ └── bot-reports.route.ts # GET /api/dataannotation-bot/reports\n│ ├── components/\n│ │ ├── BotControlPanel.tsx # Start/stop/pause UI\n│ │ ├── BotStatusCard.tsx # Compact status display\n│ │ └── HumanPatternConfig.tsx # Config sliders\n│ ├── pages/dataannotation/\n│ │ └── page.tsx # Full bot page\n│ └── config/\n│ └── addon.config.ts # Addon metadata\n├── package.json\n├── tsconfig.json\n└── README.md| Endpoint | Method | Description |
|----------|--------|-------------|
| /api/dataannotation-bot/status | GET | Current bot status |
| /api/dataannotation-bot/control | POST | Send action (start, stop, pause, resume) |
| /api/dataannotation-bot/reports?days=7 | GET | Daily reports |
| Variable | Required | Description |
|----------|----------|-------------|
| DATAANNOTATION_EMAIL | Yes | Login email |
| DATAANNOTATION_PASSWORD | Yes | Login password |
The original dataannotation-bot/ scripts were analyzed:
- human-bot.js: Uses Puppeteer with human-like typing, random delays, and anti-detection. Missing: mouse movement simulation.
- schedule.js: Human work-hour scheduling. Fully ported.
- report.js: Simple daily report generator. Enhanced with session logging.
- package.json: Dependencies: puppeteer ^24.41.0, node-cron ^4.2.1.
### Key Improvements in Addon Version
1. Bezier curve mouse movements (original had none)
2. Eased interpolation for natural acceleration
3. Micro-jitter on cursor path
4. TypeScript throughout
5. React control panel with live status
6. Aiopta addon architecture (no core changes)
Lets agents start, steer, inspect, and terminate tmux-backed coding sessions (Claude Code, opencode, codex) via a pluggable engine-adapter registry, with per-session git-worktree isolation so parallel sessions on one repo never corrupt each other, plus custom model and provider environment overrides, plus deterministic per-session project-instructions (AGENTS.md + global + explicit) load with full provenance, plus a portable Skills + Commands catalog with provenance, hash, permissions and per-workspace materialisation to engine-native paths (#132), plus versioned installer recipes with license, terms, hash and supply-chain policy for the future per-project Toolchain-Runtime (#145).
\ndevelopment/addons/developmentKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/development/engines |
| GET | /api/v1/addons/development/providers |
| GET, POST | /api/v1/addons/development/auth |
| GET, POST | /api/v1/addons/development/sessions |
| POST | /api/v1/addons/development/sessions/[id]/input |
| GET | /api/v1/addons/development/sessions/[id]/output |
| POST | /api/v1/addons/development/sessions/[id]/run |
| POST | /api/v1/addons/development/sessions/[id]/terminate |
| GET | /api/v1/addons/development/status |
| GET, POST | /api/v1/addons/development/role-profiles |
| GET, DELETE | /api/v1/addons/development/role-profiles/[role] |
| GET, POST, DELETE | /api/v1/addons/development/role-profiles/[role]/fallback |
Add-on bindet sechs Rollen an separate Engine-/Modell-/Instructions-/
Skill-/Tool-/Permissions-Bundles, versioniert pro Owner:
architect · planner · coder · qa · research · docs.Jedes Profil deklariert explizit:
\n- Engine + Modell — kein impliziter Default, jede Konfigurationslücke
schlägt fehl (INBOX-86).
- Permissions — `canRead / canEdit / canBash / canTask / canSkill /
canTool / canCommit / canMerge`; die ISSUE verbietet mehrere Kombinationen
implizit (siehe „Negative-Scope", unten).
- Limits — MaxSteps / TimeoutSeconds / Budget ( + WarnAt).
- Handoffs — gerichtete Kanten zu anderen Rollen + erlaubte Artefakte
(validated-plan, released-task-bundle, diff-bundle, test-evidence,
acceptance-rationale, run-audit).
Der Resolver materialisiert pro Rollen-Snapshot das konkrete
Engine-Setup, prüft Skills/Tools gegen die Registry und friert das
Ergebnis als unveränderlichen Snapshot ein (SHA-256 über Profil,
Instructions, Modell). Läuft der Agent, hält er seinen Snapshot für die
gesamte Laufzeit — eine Profiländerung mitten im Lauf ändert nichts am
laufenden Run, sondern erst am nächsten.
- qa darf nicht edit / commit / merge und nicht Skills aufrufen —
der Owner-Muss-Override (permissions.ownerGranted=true) wird
auditiert.
- coder darf nicht Acceptance-Kriterien als bestanden markieren
(canTask:false).
- Kein Modell/Engine-Silent-Swap: ein nicht verfügbares Modell / eine nicht
verfügbare Engine wird entweder über den explizit registrierten
Fallback (POST /role-profiles/{role}/fallback) ersetzt oder der Run
schlägt fehl (RoleProfileUnavailableError).
- Skill-/Tool-IDs, die nicht im Add-on-Registry existieren, schlagen mit
einem konkreten resource_not_found-Fehler fehl — kein stilles Ignorieren.
# Aktive Profile aller Rollen lesen\ncurl -s -H "Authorization: Bearer $AIOPTA_API_KEY" \\\n https://<instance>/api/v1/addons/development/role-profiles# Neuen Planner-Snapshot speichern (Version 2)
curl -s -X POST -H "Authorization: Bearer $AIOPTA_API_KEY" -H 'Content-Type: application/json' \\
-d '{
"role": "planner",
"version": 2,
"engine": "claude-code",
"model": "anthropic/claude-opus-4-7",
"instructions": "You are the PLANNER agent ...",
"skills": [],
"tools": [],
"permissions": {
"canRead": true, "canEdit": true, "canSkill": true,
"canBash": false, "canTask": false, "canTool": true,
"canCommit": false, "canMerge": false
},
"limits": { "maxSteps": 6, "timeoutSeconds": 1500, "budget": 4000 },
"handoffsOut": [
{ "from": "planner", "to": "coder", "artifacts": [
{ "kind": "validated-plan" }, { "kind": "released-task-bundle" } ] }
]
}' \\
https://<instance>/api/v1/addons/development/role-profiles
```
- Arbeitsverzeichnis (BUG1): cwd weglassen ⇒ auto-erzeugter Default-Workspace
(.aiopta-coding-worktrees). Fehlender Pfad ⇒ klarer Fehler mit „create it?"-Angebot
(createCwdIfMissing); Isolation braucht ein existierendes Git-Repo.
- Provider/Modell-Dropdowns (GAP3): GET /providers liefert konfigurierte
Provider + Modelle für Engine→Provider→Modell-Auswahl (kein Env-Tippen); Roh-Env
bleibt als „Advanced".
- Auth pro Engine (GAP2): GET/POST /auth — je Engine „API-Key | Login"
(Claude setup-token/OAuth, codex ChatGPT-OAuth); Token sicher pro (User,Engine),
nie geloggt; nicht-konfiguriert ⇒ graziöser Hinweis (Owner-Aktivierung Block H).
- Engines + Verfügbarkeit (#130): GET /engines liefert je Engine die
Capability-Flags und ein available-Flag. Claude Code + opencode gaten über
ihre CLI auf PATH; Codex (OpenAI) ist die 3. Engine und ist key-aware —
available:false bis der Owner einen Codex/OpenAI-Key setzt (CODEX_API_KEY /
OPENAI_API_KEY in der Addon-Config oder einen konfigurierten
openai/openai-codex-oauth Provider) oder ein ChatGPT-Login verbindet. Ein
Headless-run auf nicht-konfiguriertem Codex liefert ein sauberes
„nicht konfiguriert"-Ergebnis (kein Crash, kein Spawn). Key/Endpoint +
CLI-Container-vs-API: OPEN-DECISIONS Block H #76 (ADR-061, Addendum zu ADR-046).
Der Coding-Orchestrator verwaltet einen kanonischen Resource-Katalog aus
drei Quellen, in fester Präzedenz (project > addon > global):
- Skills liegen unter <root>/skills/<name>/SKILL.md (Markdown mit
YAML-Frontmatter: name, description, optional version, permissions).
- Commands liegen unter <root>/commands/<name>.md (Frontmatter: name,
description, prompt, optional role, engine, subtask,
permissions).
Bestehende Projektdateien werden bevorzugt gelesen statt kopiert — derproject-Source-Lookup reicht in .opencode/skills/ und nutzt OpenCode-
konforme Layouts ohne Migration.
Die Validierung lehnt ab:
\n- Unbekannte Frontmatter-Felder (jede script:/command:/exec-Field auf
einer Skill wird abgelehnt, nicht automatisch ausgeführt).
- Path-Traversal in originPath (kein .., kein Backslash auf POSIX).
- Dateien > 64 KiB oder Prompt mit NUL/Control-Bytes.
- Permissions ausserhalb des bekannten Vokabulars (files:read, git:write,
mcp:invoke, …) — keine impliziten Grants.
Pro Session materialisiert der Orchestrator freigegebene Resources in
engine-native Pfade innerhalb des Workspace (nie in den Projektbaum):
| Engine | Skills | Commands |
|---|---|---|
| opencode | .opencode/skills/<name>/SKILL.md + .agents/skills/<name>/SKILL.md (Mirror) | .aiopta-resources/opencode/commands/<name>.md |
| claude-code | unsupported (Mapping noch zu spezifizieren) | unsupported |
| codex | unsupported (Mapping noch zu spezifizieren) | unsupported |
Regeln:
\n- Materialisierung überschreibt nie eine existierende Projektdatei.
- Skill-Inhalte werden nie ausgeführt — nur als opaque Markdown geschrieben.
- Cleanup entfernt nur die im Manifest gelisteten Dateien.
- Engine-Support-Verdikte werden in MaterializeResult.refused mit Reason
protokolliert; describeActiveResources() macht die Teilfähigkeit im
Session-Status sichtbar.
- Claude Code + Codex: Materialisierung ist als unsupported markiert,
bis ein getestetes Mapping vorliegt. Der unsupported-Verdikt ist
dokumentiert und niemals ein stilles Degradieren.
- Per-User-Workspace-FS-Isolation (GAP4): zurückgestellt auf die
#136-Isolation-Foundation. Sessions sind bereits user-scoped (user_id); nur die
per-User-Dateisystem-Sandbox wird dort gebaut.
Beim Session-Start wird deterministisch ein Project-Context aus derAGENTS.md-Hierarchie des Workspaces, dem globalen Aiopta-Context
(CODING_ORCHESTRATOR_GLOBAL_AGENTS_FILE / ~/.config/aiopta/AGENTS.md) <!-- security-allow: env-var name (CODING_ORCHESTRATOR_*), not a secret -->
und einer optionalen expliziten Datei-Liste
(CODING_ORCHESTRATOR_INSTRUCTION_FILES, addon-config) geladen. Die <!-- security-allow: env-var name (CODING_ORCHESTRATOR_*), not a secret -->
kanonische, deterministisch geordnete Inhaltsmenge wird in denappendSystemPrompt der Engine gespleißt — **identisch für Claude Code,
opencode und Codex**, die jeweilige Engine entscheidet nur, ob siesystemPrompt als Flag/Env unterstützt.
| Eigenschaft | Verhalten |
|---|---|
| Präzedenz (niedrig → hoch) | global → repo-root → tieferes AGENTS.md → explizit |
| Hash je Datei | SHA-256, im Provenance-Datensatz persistiert |
| Per-File-Limit | 64 KiB (Default) — größer ⇒ Reject + Warnung |
| Total-Budget | 256 KiB (Default) — Überschreitung ⇒ truncated |
| Binary-Erkennung | NUL-Byte in den ersten 8 KiB ⇒ Reject |
| Symlink-Escape | realpath muss innerhalb des Workspace-Roots bleiben |
| Traversal | ..-Komponenten und nicht-absolute explizite Pfade ⇒ Reject |
| Request-Kontrolle | HTTP-Body kann KEINE zusätzlichen Instructions-Dateien benennen |
| Provenance-Endpoint | GET /sessions/:id ⇒ instructions (paths, hashes, status, warnings) |
Der Coding-Orchestrator definiert ein versioniertes Rezept-Schema für Coding-Tools
(Claude Code, opencode, ripgrep, …), das die zukünftige per-Project Toolchain-Runtime
(#144) mit einer prüfbaren Installationsbasis versorgt. Der Slice in #145 liefert
Schema + Validator + Planner + Provenance; der Runtime-Executor bleibt #144.
| Kind | Download | Owner-Approval | Hash | Netzwerk-Policy | Auto-Exec |
|-----------------------------|--------------------------------|----------------|---------|-----------------|-----------|
| bundled | aus Image-Layer | nein | ja | nein | n/a |
| package-manager | aus System-Paket-Manager | nein | n/a | nein | ja |
| upstream-reference | aus Upstream-URL | nein | ja | ja | ja |
| owner-url | aus Owner-freigegebener URL | ja | ja | ja | ja |
| manual | kein Download (Runbook-Text) | ja | n/a | nein | nein |
- Keine unversionierten Pakete / Images / URLs — version ist Pflichtfeld.
- Kein Hash-Bypass bei URL-Artefakten — digest.sha256 ist Pflicht für
upstream-reference und owner-url.
- Kein curl|bash / irm|iex — manual-Steps, die wie eine piped-payload aussehen,
werden abgelehnt.
- Keine automatische Terms-Akzeptanz — owner-confirmation-Lizenzen und
owner-url / manual-Rezepte benötigen ein Acknowledgement, das an
Rezept-Hash, Terms-URL+Version und Lizenz-SPDX-Id gebunden ist. Änderungen an
einem dieser Felder invalidieren die vorhandene Zustimmung.
- Keine Ausführung auf dem Core-Host — der Planner emittiert nur den
InstallPlan; die Runtime (#144) führt ihn aus.
Unter addons/development/src/lib/toolchains/installers/:
- types.ts — Recipe (diskriminierte Union über 5 kinds), InstallPlan,
Acknowledgement, NetworkPolicy, ProvenanceAttestation, SbomEntry,
ToolchainLockSlice.
- validator.ts — validateRecipe (fail-closed, sammelt alle Issues),
isHostAllowedByPolicy, isAcknowledgementApplicable.
- network-guard.ts — assertAllowedDownload (HTTPS-only, SSRF-Guard gegen
private/loopback/link-local/multicast-IPv4 + IPv6, Host-Allowlist,
Größe/Timeout-Oberflächen) und assertRedirectAllowed
(none/same-host/same-allowlist).
- acknowledgement.ts — recordAcknowledgement, revokeAcknowledgement,
isAcknowledgementFresh.
- catalog.ts — createRecipeCatalog, addRecipe (Validator-fail-closed),
listRecipes, findRecipesByTool, findRecipeFor, listHashDriftEntries.
- plan.ts — buildPlan (emittiert den InstallPlan inkl. Quell-URL,
Hash/Signatur, Lizenz/Terms, Zielruntime, Netzwerk-Policy und argv),
deriveCachePlan (Cache-/Redistribution-Policy für Uninstall/Upgrade).
- provenance.ts — buildProvenance (SLSA-Provenanz-Attestation),
buildSbom, buildToolchainLockSlice, verifyToolchainLockSlice.
addons/development/tests/unit/toolchain-installers-*.test.ts:
- types — Konstruktion + Recipe-Hash-Stabilität (Approval-Metadaten zählt
nicht zum Hash).
- validator — fail-closed für jeden Kind; Security-Fixtures für bösartige
URL/redirect/private-IP/Oversize/Hash-Mismatch/Shell-Injection.
- network — SSRF-Guard (IPv4 reservierte Bereiche + IPv6 reserved),
Allowlist-Wildcards inkl. Suffix-Angriff, Redirect-Policies.
- acknowledgement — Terms-/Hash-/License-Änderungen invalidieren
die Zustimmung (Akzeptanzkriterium "Quelle/Hash/Terms ändern sich ->
bisherige Zustimmung ungültig").
- plan — golden Plans für package-manager, upstream-reference und
manual; Cache-Policy-Surface.
- provenance — SLSA-Attestation + SBOM + Lock-Slice-Verifikation
(inkl. Reject bei Recipe-Drift).
Ausführen: npx vitest run addons/development/tests/unit/toolchain-installers-*.test.ts.
Per-User Tauchgangslogbuch. Erfasst eigene Tauchgänge, importiert CSV- und
Subsurface-XML-Bestände mit Vorschau und Deduplizierung, berechnet
Kennzahlen (Anzahl, Gesamtzeit, Max-/Durchschnittstiefe, Monatsverlauf) und
zeigt Tauchgänge mit gültigen Koordinaten auf einer Karte (geclustert, mit
Inline-SVG-Fallback wenn kein Map-Provider konfiguriert ist). Alle Daten
in einem per-User scoped Schema (ADR-054). SI-Einheiten intern (Meter,
Sekunde, UTC); Zeitzonen + Einheiten werden beim Import explizit normalisiert
und nicht stillschweigend umgerechnet.
Issue #35 liefert das CRUD-Fundament, #123 den Import-Layer, #124 die
Statistiken + Karte.
Alle Routen sind per-User scoped (auth.id aus mc-session). Eine fremde
ID liefert 404 ohne Existenz-Leak.
| Methode | Pfad | Beschreibung |
|---|---|---|
| GET | /api/v1/addons/dive-log/dives | Eigene Dives (Filter: from, to, site) |
| POST | /api/v1/addons/dive-log/dives | Neuen Dive erfassen |
| GET | /api/v1/addons/dive-log/dives/[id] | Einen Dive lesen |
| DELETE | /api/v1/addons/dive-log/dives/[id] | Einen Dive löschen |
| POST | /api/v1/addons/dive-log/imports/preview | CSV / Subsurface-XML einlesen + Vorschau |
| GET | /api/v1/addons/dive-log/imports/[id] | Vorschau-Status abrufen |
| DELETE | /api/v1/addons/dive-log/imports/[id] | Vorschau verwerfen |
| POST | /api/v1/addons/dive-log/imports/[id]/confirm | Vorschau übernehmen |
| GET | /api/v1/addons/dive-log/stats | Statistiken + Map-Punkte (Filter: from, to, site) |
GET /stats)Liefert für die per-User gefilterte Dive-Menge:
\n- Stat-Kennzahlen: totalDives, totalDurationS, maxDepthM,
avgDepthM, longestDiveS, avgDurationS, deepestSite,
divesWithCoordinates, earliestDiveAt, latestDiveAt.
- Monatsverlauf: monthly[] — Aggregate pro YYYY-MM (UTC, aufsteigend)
mit diveCount, totalDurationS, avgDepthM, maxDepthM.
- Karte: mapPoints[] (nur Dives mit gültigen Koordinaten) plus
bounds (Bounding-Box). Filter wirkt IDENTISCH auf Stats und Karte
(buildStatsResponse leitet beide aus derselben filterDives()-Menge ab).
- Map-Provider: provider.name ist "fallback" (Inline-SVG, keine
externe Verbindung) oder "iframe" (Operator hat DIVE_LOG_MAP_URL_TEMPLATE
gesetzt). providerUrl ist null im Fallback-Pfad → UI rendert die SVG.
src/lib/stats.ts + golden-fixture-getestet)totalDives = filtered.length\ntotalDurationS = Σ d.durationS\nmaxDepthM = max(d.maxDepthM)\navgDepthM = mean(d.maxDepthM)\nlongestDiveS = max(d.durationS)\navgDurationS = round(mean(d.durationS))\ndeepestSite = site of the dive with max depth\ndivesWithCoordinates = count of dives with valid lat/lon\nmonthly[i] = aggregate of dives in YYYY-MM (UTC), ascending\nmapPoints = dives with finite lat ∈ [-90,90] AND finite lon ∈ [-180,180]\nbounds = min/max of mapPoints (or null when empty)Display-Unit (metrisch/imperial) ist Anzeige-Sache. Gespeicherte SI-Werte
werden NICHT verändert (per AC: "metric/imperial Anzeige ändert nicht
gespeicherte SI-Werte"). Die StatsPanel-Komponente konvertiert beim
Rendern, nicht beim Schreiben.
Standardpfad: Inline-SVG mit geclusterten Punkten. Kein externer Call,
kein Key im Browserbundle, keine Drittanbieter-Verbindung. Die SVG-Fallback
zeichnet ein Equator-/Meridian-Raster und projiziert die Punkte über die
ermittelten Bounds. Cluster werden mit einem 1.5°-Grid gebildet (gleicher
Algorithmus wie src/lib/map-provider.ts).
Operator-Knopf: DIVE_LOG_MAP_URL_TEMPLATE (env). Akzeptiert die
Platzhalter {lat}, {lon}, {zoom}. Wird er gesetzt, liefert der/stats-Endpoint eine voll aufgelöste providerUrl, die das UI in einem
sandboxed Iframe rendert. Der Placeholder-Substitution ist opt-in:
unbekannte Platzhalter wie {apiKey} werden NICHT stillschweigend entfernt
(defensiv — der Operator steuert das Template bewusst).
Komma-getrennt, UTF-8, Header in der ersten Zeile. Spaltennamen sind
case-insensitive. Die Spalten started_at, duration, depth sind
Pflicht; alle anderen sind optional.
started_at,timezone,duration,duration_unit,depth,depth_unit,site,lat,lon,buddy,gas_mix,notes\n2024-06-15T10:30,Europe/Berlin,45,min,18,m,Lake Zurich,47.123,8.456,Hans,Air,Great viz\n2024-06-15T11:25,Europe/Berlin,52,min,22.4,m,Lake Zurich,47.123,8.456,Hans,EAN32,Einheiten:
\n- duration / duration_unit: s (Sekunden) oder min (Minuten). Default min.
- depth / depth_unit: m (Meter) oder ft (Fuß). Default m.
- started_at darf ISO-8601 mit Z, mit ±HH:MM Offset, oder naive Wand-Uhr
in der gewählten timezone sein.
<divelog> mit einem oder mehreren <dive>-Blöcken. Gelesen werden<date> (YYYY-MM-DD), <time> (HH:MM), <duration> (Sekunden), <depth>
(Meter), <location>, <gps> (lat,lon), <buddy>, <cylinder><description>
(Gas Mix) und <notes>. Namespaces, CDATA, HTML-Entities ausser &< > " ' werden nicht unterstützt — ein<malformed>-Block im Test-Fixture dokumentiert das Negativ-Verhalten.
Jede Datei wird über ihren SHA-256-Hash identifiziert. Ein zweiter Import
derselben Datei ergibt 100 % Duplikate (Re-Import ist sicher). Innerhalb
eines Imports gilt: die Zeilen-Fingerprints (started_at UTC × site ×max_depth_m × duration_s) werden aufsteigend geprüft, sodass ein
Duplikat innerhalb derselben Datei nicht zweimal geschrieben wird.
- Maximal 5 MB pro Upload
- Maximal 5 000 Zeilen pro Datei
- max_depth_m < 0, duration_s < 0 und out-of-range Koordinaten liefern
einen Zeilen-Fehler, nicht einen 400 für die ganze Datei
- Map-Punkte: nur Dives mit endlichen Koordinaten in
lat ∈ [-90, 90] / lon ∈ [-180, 180] werden projiziert
- Keine Cross-Repo-Refactors (Repository bleibt aiopta-addons)
- Keine Änderung am Auth/Login-Layer
- Keine DB-Schema-Änderung (Stats lesen nur, keine zweite Aggregationstabelle)
- Keine neuen externen Dependencies
- Keine Map-Keys im Browserbundle ohne vorhandene Credential-Verwaltung
(Inline-SVG ist der Default; ein Provider ist Operator-Opt-in via env)
- Keine medizinischen Deko-Berechnungen
**Read-only Multi-Host-Inventar und Logs (#126) + controlled start/stop/restart (#157)
+ digest-pinned image updates with health-rollback (#159) + secure multi-host
trust contract (#39: single-use enrollment, mTLS-CA, SSRF gate).**
A self-contained Aiopta addon for the homelab operator who wants to see
container, image, network, and volume state across multiple Docker hosts,
perform bounded, audited start/stop/restart actions, roll out
digest-pinned image updates that auto-rollback on health failure, and
enroll remote hosts via single-use tokens backed by an Aiopta-internal
mTLS-CA with SSRF/DNS-pinning endpoint validation — without
exposing any delete/prune/exec/compose surface. Host definitions are per-user
(ADR-054 scopedStore), and every log read + audit entry passes
through a configurable secret-redaction pipeline.
The trust anchor for talking to remote Docker hosts:
\n- Single-use enrollment tokens (24h TTL), SHA-256-hashed at rest,
plaintext returned ONCE in the POST /hosts response + the compose
snippet. Audit row on every consume.
- Aiopta-internal mTLS-CA (Ed25519, AES-256-GCM-encrypted private key
at rest). Operator CLI node scripts/aiopta-docker.cjs {status,rotate,help}.
- SSRF gate: scheme MUST be https, server-side DNS resolve, IP pinned
for the session, static CIDR blocklist (private/loopback/link-local/cloud
metadata incl. AWS 169.254.169.254 + fd00:ec2::254).
- Cross-user → 404, TLS hostname/CA failure → 404 + audit.
- Tables: docker_trust_hosts, docker_enrollments, docker_audit,
docker_ca, docker_ca_revocations (separate from #126's
docker_hosts — see the integration PR body §Documented compromise).
- Endpoints: POST hosts, audit, ca/status, enroll, enroll/:token,
hosts/:id (DELETE), hosts/:id/{test,revoke,rotate-cert},
snippet/:host_label.
\nSlice against the parent agent-trust model from #39.
This addon ships standalone with a clean adapter seam. Parent #39 will drop
in the
RemoteAgentDockerAdapter(mTLS-enrolled agent transport). Until thenthe in-memory / fake adapters serve a seeded surface so the addon is usable
end-to-end and fully testable.
### #126 — Read-only inventory + logs
- Per-user host list and inventory — the docker_hosts and
docker_inventory_cache scoped tables (ADR-054) hold host definitions +
the most recent inventory snapshot for the caller only. Foreign lookups
return 0 rows; the route layer maps that to a 404 with no existence leak.
- Paged multi-host inventory — GET /inventory returns one normalized
envelope per host. Partial-success: a down host yields reachable=false
and does not poison the rest of the payload.
- Bounded, redacted log reads — GET /logs/:host/:container enforces byte
+ line limits and returns an opaque cursor. Every line is run through the
resolved redaction-pattern set BEFORE the response leaves the server.
- Configurable redaction — GET|PUT|DELETE|PATCH /redaction-patterns is
the per-user meta-config knob for the secret-redaction pipeline.
- Status — every status response carries host + fetchedAt.
- Polling — a singleton in-process poller refreshes the inventory cache
for every enrolled user; when the addon is disabled the poller exits cleanly.
### #157 — Controlled mutations
- ✅ Start / stop / restart of allowlisted containers
- ✅ Digest-pinned image updates with health-rollback (#159) — pull + verify an
image BEFORE mutation; on unhealthy/timeout/start-failure the container rolls
back to the old digest automatically (old image preserved; no prune/delete)
- ✅ Preview snapshot + drift detection between preview and apply
- ✅ Idempotency key replay (single mutation, repeated requests are no-ops)
- ✅ Audit log with actor + host alias + container id, secrets redacted
- ✅ Per-user registry allowlist + credential redaction (no plaintext in audit)
- ❌ No delete / prune / exec / compose / image-tag mutation
- ❌ No prune/delete of foreign images (the old digest stays for rollback)
### #158 (slice 1/3, #329) — Declarative compose-schema + versioned repo loader
- ✅ JSON-Schema for Compose-project manifests at
addons/docker-manager/schema/compose-project.schema.json — single source
of truth for what a valid project.json looks like (name, version,
services[], volumes[], networks[], secrets[]).
- ✅ Versioned repo loader (loadProject(repoUrl, commitSha)) — clones the
pinned commit, validates the manifest against the schema, and verifies
the post-checkout HEAD matches the pinned SHA. Pure function for tests
via injected LoaderDeps; production deps spawn git via
child_process.execFile (no shell, argv-only).
- ✅ Typed errors (DriftError → 409, ProjectSchemaError → 422,
EmptyRepoError / MissingManifestError → 404, InvalidJsonError →
400, IoError → 502, InvalidArgsError → 400). The route layer maps
each ProjectErrorCode to its HTTP status via PROJECT_ERROR_TO_HTTP
in project-errors.ts.
- ✅ No privileged / host-network / arbitrary bind mounts — the schema
refuses them structurally (slice #330 will enforce them semantically).
- ✅ No silent overwrite of an existing project path — the loader refuses
to clobber a leftover clone and surfaces InvalidArgsError.
- ⏭ Render / Policy / Preview → slice #330.
- ⏭ Apply + Rollback → slice #331.
- ❌ No direct /var/run/docker.sock from the addon — adapter seam only
- ❌ No cross-user enumeration — foreign container ids map to 404
| Method | Path | Description |
| --- | --- | --- |
| GET | /api/v1/addons/docker-manager/health | Addon enabled + hosts count |
| GET | /api/v1/addons/docker-manager/hosts | List caller's enrolled hosts |
| GET | /api/v1/addons/docker-manager/inventory | Paginated multi-host inventory |
| GET | /api/v1/addons/docker-manager/inventory/:host | Single-host drill-down |
| GET | /api/v1/addons/docker-manager/logs/:host/:container | Bounded, redacted logs |
| GET | /api/v1/addons/docker-manager/status/:host | Per-host status (+ fetchedAt) |
| GET\\|PUT\\|DELETE\\|PATCH | /api/v1/addons/docker-manager/redaction-patterns | Per-user redaction config |
| POST | /api/v1/addons/docker-manager/containers/:id/preview | Read-only snapshot → snapshotHash |
| POST | /api/v1/addons/docker-manager/containers/:id/start | Idempotent start |
| POST | /api/v1/addons/docker-manager/containers/:id/stop | Idempotent stop |
| POST | /api/v1/addons/docker-manager/containers/:id/restart | Idempotent restart |
| POST | /api/v1/addons/docker-manager/containers/:id/update/preview | Pull + verify a digest-pinned image; return update plan |
| POST | /api/v1/addons/docker-manager/containers/:id/update/apply | Stop → start-new → health-check; auto-rollback on unhealthy |
| POST | /api/v1/addons/docker-manager/containers/:id/update/rollback | Operator-initiated rollback to old digest |
Every mutation route is wrapped in userRoute (issue #157 user-scope). The
user scope is enforced in src/lib/allowlist.ts via assertContainerForUser,
which maps a foreign id to 404 (no enumeration leak across users).
client docker-manager adapter audit\n │ POST /preview │ │ │\n │ ───────────────────►│ assertContainerForUser│ │\n │ │ ────────────────────►│ snapshot │\n │ │ │ ───────────► │\n │ {snapshotHash,K} │ audit row (success) │ │\n │ ◄───────────────────│ │ │\n │ POST /start │ │ │\n │ {snapshotHash,K} │ reserve(K) │ │\n │ │ ────────────────────►│ apply │\n │ │ ◄────────────────────│ ok / drift │\n │ {status:success} │ audit row │ │\n │ ◄───────────────────│ │ │Drift between preview and apply surfaces as HTTP 409 withstatus: "drift". Timeout surfaces as HTTP 504 with status: "timeout"
— never success (issue #157 acceptance #2).
This addon does NOT ship the agent enrollment / mTLS surface — that lives in
parent #39 / PR #261. The adapter seam is the contract between this addon and
the trust layer. Implementations shipped today:
- FakeDockerAdapter (#126) — pure in-memory, hermetic. Used by the #126
inventory unit suite. NEVER opens a socket.
- createInMemoryDockerAdapter (#157) — fully deterministic mutation adapter
for the #157 unit suite; no real network, no real Docker.
- LocalDockerAdapter / RemoteAgentAdapter — land with parent #39.
- The only Docker-mutating routes are start/stop/restart (#157); the
redaction-patterns non-GET routes are per-user meta-config, not Docker
mutations.
- credentialRef (the pointer to the Core Credential Store) is masked before
any host is sent to a client; the raw reference NEVER leaves the server.
- Every Docker-host operation is per-user via scopedStore(userId); foreign
users get 0 rows + 404.
- Per-host failure isolation — a down host does not poison the rest of the
dashboard.
- Audit entries carry no secret material (opaque-token + secret-key patterns
are redacted before logging).
# Local validation\n./scripts/validate-addons.sh# Unit tests
npx vitest run addons/docker-manager/tests/unit
```
The adapter seam lets #157 ship standalone; the agent transport drops in once
#39 lands without touching this addon's route handlers.
Initial release — ships the trust anchor for multi-host Docker
management. Children #126–#159 build the read/mutate/compose/img
surfaces on top.
- addon.json manifest + src/manifest.ts runtime extension (scope: list, test, enroll, revoke, rotate-cert, audit, ca/status, snippet/{label}).
- Per-user scopedStore('docker_hosts'), scopedStore('docker_enrollments'), scopedStore('docker_audit') (ADR-054).
- Instance-level docker_ca + docker_ca_revocations (CRL).
- Single-use enrollment tokens: SHA-256(token) stored; plaintext
returned ONCE in POST /hosts response and embedded in the
docker-compose.yml snippet.
- AES-256-GCM envelope encryption (src/lib/crypto.ts) for the CA
private key + optional cached agent private key.
- mTLS CA primitive (src/lib/mtls-ca.ts) — generation, agent cert
issuance, signature verify (with Ed25519-aware crypto.sign /
crypto.verify), rotation, CRL pinning.
- Endpoint validator (src/lib/endpoint-validator.ts) — SSRF gate
(private / loopback / link-local / cloud-metadata blocklist +
DNS-pinning) + assertSameUser cross-user guard.
- Adapter seam (src/lib/adapter.ts) — typed Success / Timeout /
Refuse / Revoke fakes + liveAdapter (TLS-validated) +
outcomeFromAdapter() audit-log mapper.
- docker-compose.yml snippet renderer (src/lib/compose-snippet.ts)
with security invariants (no ports:, no privileged: true, no
network_mode: host).
- 8 API route handlers under src/app/api/v1/addons/docker-manager/.
- UI dashboard (src/components/DockerManagerDashboard.tsx) with
enroll form, host list, compose snippet viewer, audit log, and
per-host actions.
- Operator CLI (scripts/aiopta-docker.cjs {status, rotate, help})
for CA rotation.
- No /var/run/docker.sock mount from Aiopta to remote hosts.
- Cross-user → 404 (no enumeration leak).
- TLS hostname / CA failure → 404 + audit row.
- DNS-pinning (server-side resolve, IP pinned for the session).
- Agent private key (when cached for re-rotate) encrypted at rest
via AES-256-GCM.
- redactEnvelopes() strips enc:v1:... blobs from any error path.
- 6 test files, 77 passing tests.
- compose-snippet.test.ts (12) — render + security invariants + sha256.
- endpoint-validator.test.ts (19) — SSRF, DNS-pinning, cross-user,
CIDR membership for v4/v6.
- crypto.test.ts (15) — round-trip + tamper detection + nonce
uniqueness + weak-key guard + envelope redaction.
- mtls-ca.test.ts (9) — CA gen, agent cert, rotation, verify
round-trip, cross-CA defense, expiry.
- adapter.test.ts (11) — fake outcomes + audit-log mapping.
- store.test.ts (10) — schema idempotency + per-user scoping +
single-use tokens + CRL pinning + CA rotation.
npm run validate:addons ✅node --check scripts/aiopta-docker.cjs ✅Slice 2 of the Docker Manager declarative Compose-Deploy epic. Ships
the deterministic render pipeline + 4 standard policy rules + the
preview endpoint. Slice 1 (#329) owns the JSON-Schema + repo-loader;
slice 3 (#331) will wire the preview output into the apply path.
- src/lib/compose-project.ts — ComposeProject types (services,
volumes, networks, secrets, mounts) + validateProjectShape()
(pure schema validator that collects ALL issues in one pass) +
loadProject({project, expectedCommitSha}) (deep-frozen validator
with drift detection via DriftError) + projectContentHash()
(canonical JSON SHA-256, deterministic across key-order changes).
This file is the shared contract between slice 1 (loader) and slice
2 (renderer).
- src/lib/render.ts — deterministic renderProject(project, vars)
→ canonical docker-compose.yml + configHash + used placeholder
list. Pure function: equal inputs always yield equal output.
PLACEHOLDER_RE = /\\$\\{([A-Z][A-Z0-9_]{0,63})\\}/g is the only
recognised placeholder shape; suspicious placeholders are passed
verbatim so the policy engine can flag them. redactRenderedYaml()
+ previewRenderedConfig() strip secret-shaped values
(password=..., token=..., api_key=..., secret=..., URL with
userinfo, opaque ≥32-char tokens) before returning to the caller.
- src/lib/policy.ts — checkPolicy(project) runs the four
standard rules and returns typed PolicyViolation[]:
- R1 — privileged: true → block
- R2 — network_mode: host → block
- R3 — dangerous bind mounts (/, /etc, /proc, /sys,
/dev, /boot, /root, /home, /var/run/docker.sock,
/var/lib/docker); catches /etc/../var/run/docker.sock
traversal evasion
- R4 — inlined secrets in env / command / labels; suspicious
placeholders (${../etc/passwd}, ${$(rm -rf /)}) → block,
non-standard placeholder shape → warn
- src/lib/preview-pipeline.ts — runPreview(input) glues
load → render → policy → redact into a typed PreviewResult.
The route layer uses it directly; slice 3 (#331) calls the same
helper before apply.
- POST /api/v1/addons/docker-manager/preview — preview endpoint
(200 on clean / 403 on block-severity violations / 409 on drift /
400 on bad input / 401 on no-auth). Writes one audit entry per
accepted request: success / rejected (with violation summary)
/ drift (with both SHAs). No secrets in the audit reason
field — redaction runs before the entry is appended.
- Tests — 4 new test files (52 new assertions total):
compose-project.test.ts (19), render.test.ts (15),
policy.test.ts (16), preview-pipeline.test.ts (13),
preview-route.test.ts (15). All pass via vitest
(npx vitest run addons/docker-manager/tests/unit/).
- Slice 1 (#329): Git-clone repo loader + JSON-Schema file. Slice 2
consumes the typed ComposeProject slice 1 produces.
- Slice 3 (#331): POST /api/v1/addons/docker-manager/apply with
partial-failure reconcile + rollback plan. Slice 3 reads the
preview's configHash + violations[] and refuses apply when
blocked === true.
- The ComposeProject type lives in slice 2 even though slice 1 owns
the loader — the render + policy modules need a typed shape and
putting it here means slice 1 imports this module. Slice 1's
JSON-Schema becomes a hand-written mirror of the runtime shape,
so a drift fails fast in validateProjectShape.
Run a print-on-demand / dropshipping business from inside Aiopta — browse a supplier
catalog, apply margin rules to turn supplier cost into retail price, place draft orders, and
explicitly fulfill them. Usable by agents (via the addon API) and by humans (via the management
page). Suppliers: Printful and Printify.
- The suppliers are external SaaS APIs — there is NO container. Printful (https://api.printful.com)
and Printify (https://api.printify.com/v1) are third-party SaaS, not self-hostable tools, so —
unlike the WordPress addon (ADR-009/010) — this addon declares no container. Each supplier
client (src/lib/printful-client.ts, src/lib/printify-client.ts) is a thin HTTPS client behind a
small common interface (src/lib/supplier.ts: SupplierClient). This is the same pattern as the
LLM providers (a client to a third-party API using the owner's key).
- Owner's key from Aiopta-config, never hard-coded, never logged. Each client reads its API key via
getAddonConfiguration("dropshipping") (PRINTFUL_API_KEY / PRINTIFY_API_KEY). The vendor base
URL is a compile-time constant in the client — never a user-entered host. The key is sent as a
Bearer token and is never written to logs. When a key is missing, the client returns a clear
400 SupplierError (it never throws uncaught and never calls a default host).
- No money moves without an explicit fulfill call. Creating an order produces a draft only.
Fulfillment is a separate, explicit endpoint (POST /orders/{id}/fulfill) that forwards the order
to the supplier (/orders/{id}/confirm for Printful, /send-to-production.json for Printify). Real
fulfillment requires the owner's funded supplier account; until funded the supplier rejects
confirmation and the upstream error is surfaced.
- Talks to other addons only via the Aiopta API. The optional WooCommerce bridge
(src/lib/woo-bridge.ts) calls the wordpress addon's Woo endpoints
(/api/v1/addons/wordpress/products, .../orders/{id}) through the Aiopta API — never WooCommerce or
the supplier directly — and fails soft if the wordpress addon is absent.
| Key | Required | Purpose |
|-----|----------|---------|
| PRINTFUL_API_KEY | for Printful | Printful API token (Bearer). Stored is_secret=1. |
| PRINTFUL_STORE_ID | optional | Store id for account-level Printful tokens (X-PF-Store-Id). |
| PRINTIFY_API_KEY | for Printify | Printify personal access token (Bearer). Stored is_secret=1. |
| PRINTIFY_SHOP_ID | optional | Shop id; auto-resolved from /shops.json when absent. |
| MARGIN_RULES | optional | JSON margin rules; defaults to +40% charm-rounded to .99. |
Set them with setAddonConfiguration("dropshipping", { PRINTFUL_API_KEY: "…" }). Until at least one
key is set, /status reports the supplier as not-configured and product/order calls return a clear
400.
All routes are namespaced under /api/v1/addons/dropshipping/ and require auth.
GET /status → configured suppliers + connection probe\nGET /products?supplier=printful → list catalog products (with margin-applied retailPrice)\nPOST /products { productId, supplier?, syncWoo? } → import a product (optional Woo publish)\nGET /orders?supplier=&status= → list orders\nPOST /orders { items[], recipient{…}, supplier? } → create a DRAFT order (no charge)\nGET /orders/{id}?supplier= → order status + tracking\nPOST /orders/{id}/fulfill { supplier? }→ EXPLICITLY fulfill (forward to supplier; moves money)\nGET /fulfillments → open/in-progress orders across suppliers + revenue\nPOST /fulfillments { orderId, supplier? } → re-sync one order's status + tracking\nGET /margins → active margin rules + worked example\nPUT /margins { default:{percent,fixed,minPrice?,roundTo?}, perSupplier?{…} } → set rulesResponses use the { "success": true, "data": … } envelope. On failure read error + the HTTP
status (a 400 means the supplier key is not set; the upstream vendor status is preserved otherwise).
src/lib/pricing.ts is pure and unit-tested. A MarginRule turns a supplier base cost into a
retail price: retail = max(cost*(1+percent/100) + fixed, minPrice), then optional charm-rounding
(roundTo, e.g. .99). Per-supplier overrides are supported via perSupplier. Default rule: +40%,
charm-rounded to .99 (so cost 20 → retail 28.99).
addons/dropshipping/\n├── addon.json # Manifest (page + widget + endpoints + skills; NO container)\n├── README.md\n├── SKILL.md # Agent skill\n├── src/\n│ ├── manifest.ts # Extension (dual-registration: routes + page; string-literal handlers)\n│ ├── page.tsx # Management UI (Products / Orders / Fulfillments / Margins)\n│ ├── widget.tsx # Dashboard widget (open fulfillments + revenue, declarative)\n│ ├── lib/\n│ │ ├── supplier.ts # Common SupplierClient interface + SupplierError\n│ │ ├── printful-client.ts # Printful SaaS client (key from Aiopta-config)\n│ │ ├── printify-client.ts # Printify SaaS client (key from Aiopta-config)\n│ │ ├── http.ts # Shared Bearer fetch (constant base URL; key never logged)\n│ │ ├── suppliers.ts # Registry + /status probe\n│ │ ├── pricing.ts # Pure margin / retail-price math\n│ │ ├── margins-store.ts # Margin rules persisted via Aiopta addon-config\n│ │ └── woo-bridge.ts # OPTIONAL WooCommerce bridge via the wordpress addon's Aiopta-API\n│ └── app/api/v1/addons/dropshipping/{status,products,orders,orders/[id],orders/[id]/fulfill,fulfillments,margins}/route.ts\n└── tests/unit/ # manifest validity + pure pricing + supplier clients (fetch+config mocked)The addon code + routes work the moment the owner stores a supplier key. Tracked indocs/OPEN-DECISIONS.md:
\nTODO(owner):
dropshipping-supplier-keys— create a Printful and/or Printify API key and storeit in Aiopta addon-config (
PRINTFUL_API_KEY/PRINTIFY_API_KEY). No secret is committed. Until set,
/statusreports not-configured and calls return a clear 400. Real fulfillment additionallyrequires a funded supplier account.
MIT
", "byteSize": 6745 } } }, { "id": "email-marketing", "uuid": "c9f6a2c1-0716-4f47-91f4-dbc7c437c654", "name": "E-Mail-Marketing (Listen, Kampagnen, Templates, Sequenzen)", "version": "1.0.5", "description": "E-Mail-Marketing über die in Aiopta konfigurierte E-Mail (SMTP/ESP, wie lead-gen): Listen & Abonnenten mit Double-Opt-in, wiederverwendbare Templates, Kampagnen mit Segmentierung, Drip-Sequenzen sowie Öffnungs-/Klick-/Bounce-Tracking. Lokale SQLite ist die Quelle der Wahrheit; ohne konfigurierten Versand läuft das Addon graceful (Listen/Abonnenten/Templates anlegbar, Versand meldet 'zuerst E-Mail konfigurieren', nie ein 500). Jede Marketing-Mail trägt einen Abmeldelink; unbestätigte Adressen werden nie angeschrieben. Confirm/Unsubscribe/Open/Click sind öffentlich, aber tokengeschützt; der Klick-Redirect leitet nur auf die gespeicherte URL um (kein Open-Redirect). ADR-042.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "lists", "subscribers", "double-opt-in", "templates", "campaigns", "sequences", "segmentation", "open-tracking", "click-tracking", "bounce-tracking", "unsubscribe" ], "tags": [], "download": "/artifacts/email-marketing-1.0.5.zip", "sha256": "200c0613fc02935fc27b4e873159e74de2b5b56225491d4e3d690069390be7e1", "size": 267743, "page": { "id": "email-marketing-page", "path": "/addons/email-marketing", "name": "E-Mail-Marketing", "icon": "📣", "section": "Money", "component": "@addons/email-marketing/src/page" }, "deprecated": false, "endpoints": [ "/api/v1/addons/email-marketing/status", "/api/v1/addons/email-marketing/lists", "/api/v1/addons/email-marketing/lists/:id", "/api/v1/addons/email-marketing/lists/:id/subscribers", "/api/v1/addons/email-marketing/subscribers/:id", "/api/v1/addons/email-marketing/templates", "/api/v1/addons/email-marketing/templates/:id", "/api/v1/addons/email-marketing/campaigns", "/api/v1/addons/email-marketing/campaigns/:id", "/api/v1/addons/email-marketing/campaigns/:id/send", "/api/v1/addons/email-marketing/sequences", "/api/v1/addons/email-marketing/sequences/:id", "/api/v1/addons/email-marketing/sends/:id/bounce", "/api/v1/addons/email-marketing/public/confirm", "/api/v1/addons/email-marketing/public/unsubscribe", "/api/v1/addons/email-marketing/public/open", "/api/v1/addons/email-marketing/public/click", "/api/v1/addons/email-marketing/widget" ], "skills": [ { "name": "email-marketing-overview", "displayName": "E-Mail-Marketing: Status & Übersicht", "description": "Liest den Versand-Status (konfiguriert? Provider/From-Domain, ohne Secrets) und die Marketing-Übersicht (Listen, Abonnenten nach Opt-in-Status, Templates/Kampagnen/Sequenzen, letzte Öffnungsrate). Reiner Lesezugriff — versendet nichts.", "permissions": [ "addons/email-marketing/status" ], "endpoint": "/api/v1/addons/email-marketing/status", "scripts": [] }, { "name": "email-marketing-lists", "displayName": "E-Mail-Marketing: Listen & Abonnenten", "description": "Listet/erstellt Listen und fügt Abonnenten hinzu (mit Double-Opt-in: neue Adressen sind 'pending' und bekommen eine Bestätigungs-Mail). Unbestätigte Adressen werden nie angeschrieben. Versand der Bestätigung braucht konfigurierte E-Mail (sonst bleibt der Abonnent 'pending', kein 500).", "permissions": [ "addons/email-marketing/lists", "addons/email-marketing/status" ], "endpoint": "/api/v1/addons/email-marketing/lists", "scripts": [] }, { "name": "email-marketing-templates", "displayName": "E-Mail-Marketing: Templates", "description": "Listet/erstellt/bearbeitet wiederverwendbare E-Mail-Templates (Betreff + HTML/Text-Body mit Merge-Feldern wie {{name}}).", "permissions": [ "addons/email-marketing/templates" ], "endpoint": "/api/v1/addons/email-marketing/templates", "scripts": [] }, { "name": "email-marketing-campaigns", "displayName": "E-Mail-Marketing: Kampagnen", "description": "Erstellt Kampagnen (Liste/Segment + Template) und versendet sie. Der Versand iteriert NUR bestätigte, segment-passende Abonnenten, respektiert eine Sendegrenze, hängt an jede Mail einen Abmeldelink und fügt Öffnungs-/Klick-Tracking hinzu. Ohne konfigurierte E-Mail liefert der Versand ein klares 400 ('zuerst E-Mail konfigurieren'), nie ein 500.", "permissions": [ "addons/email-marketing/campaigns", "addons/email-marketing/status" ], "endpoint": "/api/v1/addons/email-marketing/campaigns", "scripts": [] }, { "name": "email-marketing-sequences", "displayName": "E-Mail-Marketing: Sequenzen", "description": "Listet/erstellt Drip-Sequenzen (mehrere Mails zeitversetzt, Trigger: nach Bestätigung) und aktiviert/deaktiviert sie.", "permissions": [ "addons/email-marketing/sequences" ], "endpoint": "/api/v1/addons/email-marketing/sequences", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "Listen & Abonnenten (mit Double-Opt-in), wiederverwendbare Templates, Kampagnen mit
Segmentierung, Drip-Sequenzen sowie Öffnungs-/Klick-/Bounce-Tracking — versendet über die in
Aiopta konfigurierte E-Mail (SMTP/ESP, derselbe Mail-Pfad wie lead-gen).
\nMoney-Stufe-1 · ADR-042 · Connector-Pattern (kein Container — nutzt Aiopta instances Mail) · #69 / INBOX-2.
- Listen & Abonnenten — Listen anlegen; Abonnenten hinzufügen/importieren (Name/E-Mail/Attribute/
Tags). Opt-in-Status pending → confirmed → unsubscribed | bounced.
- Double-Opt-in — neue Abonnenten sind pending und erhalten eine Bestätigungs-Mail mit einem
tokengeschützten Confirm-Link; eine öffentliche Confirm-Route setzt sie auf confirmed. Unbestätigte
Adressen werden nie in Kampagnen angeschrieben.
- Templates — Betreff + HTML/Text-Body mit Merge-Feldern ({{name}}, {{email}}, beliebige
Attribute).
- Kampagnen — Liste/Segment + Template wählen, anlegen, senden (oder planen). Der Versand iteriert
nur bestätigte, segment-passende Abonnenten, respektiert eine Sendegrenze (sendCap + Tageslimit),
hängt an jede Mail einen Abmeldelink und fügt Öffnungs-/Klick-Tracking hinzu.
- Sequenzen — geordnete Mail-Serie mit Zeitversatz; Trigger: nach Bestätigung (on-confirm).
- Tracking — Öffnung (1×1-Pixel über eine öffentliche Route, token = Send-ID), Klick (Links
werden auf eine öffentliche Redirect-Route umgeschrieben, die den Klick erfasst und dann auf die
gespeicherte Ziel-URL 302-weiterleitet — kein Open-Redirect), Bounce (Bounce-Zustand +
Route/Hook zum Markieren).
- Segmentierung — filtere Abonnenten nach Tag/Attribut/Aktivität (geöffnet/geklickt) für die
Kampagnen-Zielgruppe.
- Abmeldelink in jeder Marketing-Mail (tokengeschützte öffentliche Route, ein-Klick, ohne Login) —
CAN-SPAM/GDPR, nicht verhandelbar.
- Double-Opt-in ist Standard; unbestätigte Adressen werden nie massenhaft angeschrieben.
- Tracking-Pixel / Klick-Redirect / Confirm / Unsubscribe sind öffentlich, aber tokengeschützt
(unrater Token → erfassen → handeln). Das Redirect-Ziel ist ausschließlich die gespeicherte URL
(kein Open-Redirect / SSRF über ein vom Empfänger geliefertes Ziel — es gibt keinen Ziel-Parameter im
Request).
- Secrets (SMTP/ESP) kommen aus Aiopta-Config, nie geloggt. In Logs/URLs steht keine PII außer dem
opaken Token.
- Ohne konfigurierte E-Mail liefert der Versand ein klares 400 ("zuerst E-Mail konfigurieren"); die
Seite zeigt den not-configured-EmptyState (CTA → /settings/connections), nie ein 500.
- Pro-Benutzer-Isolation (#142 / INBOX-59, ADR-054): jede Liste, jeder Abonnent, jedes Template,
jede Kampagne/Sequenz/Send/Tracking-Zeile trägt user_id NOT NULL und gehört dem **erstellenden
Benutzer** (server-seitig aus auth.id gestempelt, ein Client-Owner wird ignoriert). Lesen/Ändern/
Senden/Löschen ist auf die eigenen Daten gescoped; eine fremde id ist ein 404 (nie 403). Das
Tageslimit ist pro Benutzer. Die öffentlichen, tokengeschützten Routen sind die einzige Ausnahme
(login-frei, nur durch den unraten Token autorisiert).
SMTP: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_SECURE, SMTP_FROM — oder ein ESP:ESP_PROVIDER + ESP_API_KEY + ESP_FROM. Optional: SEND_DAILY_LIMIT (Standard 2000). Secrets werden
mit is_secret=1 gespeichert, maskiert, nie geloggt. (Siehe OPEN-DECISIONS email-marketing-mail-config.)
- Quelle der Wahrheit: lokale SQLite (email_marketing_*), erstellt in install(), entfernt in
uninstall() über Aiopta instances getDb().
- Mail-Pfad: src/lib/sender.ts liest die Config wie lead-gen (getAddonConfiguration) und versendet
per nodemailer (lazy import) — kein neuer SMTP-Layer.
- Pure Kerne (unit-getestet, ohne DB): Opt-in-Statusmaschine, Merge-Felder, Segment-Prädikat,
Abmelde-Footer, Klick-Link-Rewrite (gespeicherte Ziel-URL).
- Öffentliche Routen: src/proxy.ts (isEmailMarketingPublic) lässt GETs unter /public/ ohne
Credential durch — derselbe Mechanismus wie der file-hosting-Serve-Read.
- Zustellbarkeit (Sending-Domain + SPF/DKIM/DMARC) — der Owner stellt die Mail-Infrastruktur; das
Addon versendet über die konfigurierte SMTP/ESP.
- Bounce-Ingestion (IMAP-Postfach oder Provider-Webhook) — der Bounce-Zustand + die
POST /sends/:id/bounce-Route/Hook shippen heute; der Ingestion-Transport ist Owner-Infra.
Beides ist nicht blockierend: das Addon läuft graceful ohne sie.
\naddons/email-marketing/tests/unit — Store (Opt-in-Statusmaschine + Double-Opt-in-Confirm-Flip,
confirmed-only-Audience, Tracking, Bounce-Flip), Sender (gemockte SMTP: confirmed-only, Abmeldelink in
jeder Mail, Cap, Klick-Rewrite gespeicherte URL, ohne SMTP → graceful 400), öffentliche Routen
(Confirm/Unsubscribe-Flip, Open-Pixel, Klick-Redirect nur auf gespeicherte URL + fremdes Ziel abgelehnt),
Evil-User-Isolation (isolation.test.ts — Benutzer A/B, B sieht/ändert/sendet/löscht A's Listen/
Abonnenten/Templates/Kampagnen/Sequenzen nicht; Owner aus auth.id gestempelt; Route-Layer 401 unauth +
404 für fremde id), Proxy-Allow-Liste, Manifest-Audit.
Kapselt die Quotation-Ebene deiner ERPNext-Instanz (Frappe v16) in Aiopta —
als dual-mode connect-Addon ohne Container. Geteilt zwischen LayerY
(Auto-Slicing, #1116) und Buchhaltung (#1055); ersetzt die n8n-Workflows
WF05/WF06/WF03.
\nOhne
baseUrltut dieses Addon nichts. Es gibt keinen Vorgabewirt undkeinen stillen Rückfall (#1220): trage die Basis-URL deiner eigenen
ERPNext-Instanz in den Addon-Einstellungen ein, sonst antworten die Routen
mit „nicht konfiguriert" — und es geht kein einziger Netzruf hinaus.
Browser/Agent ──HTTPS──▶ Aiopta (dieses Addon) ──HTTPS──▶ ERPNext (konfigurierte baseUrl)\n ├─ Dashboard (native DS-Seite) /quotation/{name}\n ├─ API-Routen (userRoute) /quotation/{name}…\n └─ MCP-Server (erpnext-tools) read-only- Natives Dashboard (src/page.tsx, ui.mode: "aiopta"): Quotation
über Bestellnummer (po_no) oder Beleg-Name suchen, Kunde/Status/docstatus
und Positionen anzeigen, Preise setzen, submit, senden, Verloren markieren,
PDF öffnen. Ausschließlich @aiopta/ui-Komponenten. Der Browser
kontaktiert ERPNext nie direkt.
- API-Routen (src/app/api/v1/addons/erpnext/*): zentrale Auth via
userRoute (Session-Cookie oder Bearer/X-API-Key Agent-Key). Es gibt
eine Pfadfamilie: quotation/{name}/…. Der Addon-Client
(src/lib/erpnext-client.ts) spricht Frappe-REST/api/method mit
Authorization: token <api_key:api_secret>.
- Rechtestufen (Ticket #1174, #1187): read (lesen, PDF-URL) <
write (Preise setzen, Verloren) < submit (submit 0→1, E-Mail-Senden).
Das ist der tier in capabilityDeclarations[]
(standard/elevated/highest) samt zugehöriger Permission; Durchsetzung
core-seitig. **Nicht zu verwechseln mit dem Addon-Trust-Level nach
ADR-062** (trusted/standard/restricted) — der ist instanzweit, wird
vom Admin gesetzt, steht nicht im Manifest und wird am Dispatch über
isMethodAllowedForTrust erzwungen. Bis 0.2.0 nannte diese Zeile ADR-060;
das ist die ADR zur Audit-Export-Aufbewahrung und war schlicht die falsche
Nummer. Die Routen erzwingen die docstatus-Invariante **kein implizites
Submit**: prices/items lässt docstatus unangetastet, Submitten läuft NUR
über die submit-Route.
- MCP-Server (mcp/servers/erpnext-tools/server.mjs, Node-STDIO):
strikt read-only nach #399 (toolPolicy.mode: read-only) — quotation_get
und quotation_find_by_po. Schreibende Tools kommen erst, wenn der
Vorschau/Bestätigungs-Vertrag (addons#930) etabliert ist.
| Key | Typ | Default | Beschreibung |
| --- | --- | --- | --- |
| baseUrl | text | — (Pflicht) | Basis-URL deiner ERPNext-Instanz, z. B. https://erp.example.org. Kein Vorgabewert, kein Rückfall — siehe unten. |
| apiToken | password (secret) | — | ERPNext-API-Token, Format api_key:api_secret. Wird als Authorization: token <wert> versendet und verlässt den Server nie. |
| printFormat | text | ` (leer) | ERPNext-Print-Format für die Quotation-PDF, z. B. Quotation with Item Image`. Leer = Standard-Print-Format der Instanz. |
baseUrl Pflicht ist und keinen Default hatBis einschliesslich Version 0.2.0 trug baseUrl die Adresse **einer
bestimmten Installation** als Vorgabewert — und fiel bei leerem Feld still
darauf zurück. Das waren zwei Fehler in einem:
1. **Der Wirt eines Betreibers stand im Code eines Addons, das andere
installieren.** Wer das Addon aus dem Marketplace zog und das Feld nicht
füllte, schickte sein apiToken an einen Server, der ihm nicht gehört.
2. Der Rückfall war still. Eine leere Einstellung führte zu einem Netzruf
statt zu einer Meldung; der Aufrufer bekam 401/404 von einer fremden
Instanz und suchte den Fehler bei sich.
Heute gilt: leer bleibt leer. callErp wirft ErpConfigError vor jedemfetch, der MCP-Server fails CLOSED ohne AIOPTA_CONFIG_BASEURL. Das
Beispiel https://erp.example.org steht in der description des Settings,
nicht in seinem default. Fehlt das http://- bzw. https://-Schema, ist
das ebenfalls ein Konfigurationsfehler mit eigener Meldung — sonst käme der
häufigste Tippfehler als „ERPNext nicht erreichbar" heraus und man suchte bei
einem Server, der läuft.
\nWo die Pflicht durchgesetzt wird: zur Laufzeit, nicht im Formular.
settingsSchematrägt zwarrequired: true, aber das Core-Schema fürSettings-Felder kennt diesen Schlüssel nicht
(
aiopta-core/src/lib/addons/manifest.ts,addonSettingsFieldSchema) undverwirft ihn beim Parsen — genau wie beim
apiToken, der es seit jeherebenso hält. Das Formular hindert also niemanden am Speichern eines leeren
Feldes; das Addon antwortet danach mit „nicht konfiguriert".
/pdf und /send ziehen die PDF über dasselbe Print-Format. Rangfolge:
?format=… bzw. Body-Feld format),printFormat,Warum das ein Parameter ist und keine Konstante: die LayerY-Druckzentrale
zeigt dem Betreiber vor dem Versand genau die PDF, die der Kunde bekommt —
und die kommt dort aus Quotation with Item Image (n8n-Workflow 09). Ohne
den Parameter wären Vorschau und Kundenanhang zwei verschiedene Dokumente,
und der Unterschied fiele erst beim Kunden auf. Der Default bleibt leer:
für bestehende Installationen ändert sich nichts, solange niemand das
Setting füllt.
POST /quotation/{name}/items nimmt je Eintrag {name?, item_code?, rate}:
| Schlüssel | Trifft | Wofür |
| --- | --- | --- |
| name | genau eine Unterzeile (items[].name der Quotation, im ERP ein Hash) | der genaue Weg |
| item_code | jede Position mit dieser Artikelnummer | Rückfall für bestehende Aufrufer (#1055) |
Sind beide gesetzt, gilt name — der genauere Schlüssel schlägt den
gröberen. rate muss eine Zahl sein; "36.98" wird abgelehnt, statt das
Dezimaltrennzeichen zu raten.
Drei Fälle, in denen kein Preis gesetzt wird — und das gesagt wird:
\n| Fall | Antwort |
| --- | --- |
| Schlüssel gehört nicht zu diesem Beleg | 404 mit Nennung des Schlüssels |
| Schlüssel trifft mehrere Positionen | 400 „…ist mehrdeutig" |
| zwei Einträge treffen dieselbe Position | 400 |
Die Zuordnung steht vollständig fest, bevor die erste Zeile verändert
wird: entweder alle Preise oder keiner. Ein halb bepreister Beleg wäre
schlimmer als ein unbepreister, weil er von aussen fertig aussieht.
Warum das ein eigener Schlüssel sein muss (addons#1211): bei LayerY
nummeriert der item_code nur durch (LaY-3D-3440-01, LaY-3D-3440-02) und
sagt nichts darüber, welche Datei die Zeile meint. Zwei Positionen mit
vertauschten Preisen fänden über den item_code nicht auseinander — am
06.08.2026 hat diese Fehlerklasse 141,83 EUR statt 36,98 EUR ergeben.
Für bestehende item_code-Aufrufer ändert sich genau eine Sache: trifft
ein item_code mehrere Zeilen, ist das jetzt ein Fehler. Bis 0.2.0 bekamen
dann alle diese Zeilen stillschweigend denselben Preis.
GET /quotation/{name} liefert — und was bewusst nichtDie Antwort trägt den ERPNext-Beleg (alle Felder inkl. items), dazu:
| Feld | Bedeutung |
| --- | --- |
| pdfUrl | Adresse der /pdf-Route dieses Belegs |
| erpMailAccount | {outgoing, grund, konto} — gibt es ein Email Account mit enable_outgoing = 1? |
erpMailAccount.outgoing ist dreiwertig, und das ist der Punkt:
| Wert | Heisst |
| --- | --- |
| true | Es gibt mindestens ein Konto mit Ausgang (konto nennt das erste). |
| false | Es gibt keines. Eine Aussage. |
| null | Die Frage wurde nicht beantwortet — grund sagt warum. |
false und null zusammenzuwerfen wäre der teuerste Kurzschluss dieses
Addons. Der häufigste Grund für null ist ein HTTP 403 auf Email Account,
weil der API-Nutzer dieses DocType nicht lesen darf. Als false gemeldet
sähe eine funktionierende Instanz aus wie eine ohne Postausgang — und
niemand käme je auf die Idee, ein Recht zu prüfen.
Die Zusatzfrage lässt die Route nie scheitern: wer den Beleg sehen will,
bekommt ihn auch dann, wenn das Mailkonto gerade unbeantwortbar ist.
bestellung kommt NICHT von hier (addons#1213)Der abgelöste n8n-Workflow 08 lieferte drei Blöcke: quotation,bestellung (WooCommerce) und erp_mail_konto. Dieses Addon liefert die
erste und die dritte Frage. Den **WooCommerce-Stand holt der Aufrufer beimwordpress-Addon**:
GET /api/v1/addons/wordpress/orders/{order_id}Warum nicht hier — drei Gründe, jeder nachprüfbar:
\n1. Die Route existiert dort schon. addons/wordpress v1.2.1 führt die
Capability woocommerce-orders und genau diese Route. Hier wäre sie eine
zweite Umsetzung derselben Frage.
2. Es wären Shop-Zugangsdaten an einem zweiten Ort. Dieses Addon kennt
heute nur baseUrl + apiToken (ERPNext). WooCommerce-Consumer-Key und
-Secret hier abzulegen hiesse: dieselben Geheimnisse zweimal, mit zwei
Rotationszeitpunkten.
3. **Eine addonDependencies-Kante auf wordpress bräche die
Buchhaltung.** Nach ADR-047 endet eine unerfüllte required-Kante in
addon_dependencies_unmet (HTTP 409). Dieses Addon wird zwischen LayerY
(#1116) und der Buchhaltung (#1055) geteilt — letztere hat kein
WooCommerce und könnte es dann nicht mehr installieren.
Beide Addons liegen hinter derselben Aiopta-Adresse und derselben Auth; der
zweite Ruf kostet keinen neuen Zugang und kein neues Geheimnis.
sent: false kommt — und was der Aufrufer dann tun sollPOST /quotation/{name}/send nimmt `{subject?, message?, format?,
submitIfDraft?}` und antwortet mit{name, sent, grund, submitted, docstatus, detail}.
Zwei Antwortklassen, und sie bedeuten Verschiedenes:
\n| Antwort | Heisst | Der Aufrufer soll |
| --- | --- | --- |
| 200, sent: true | ERPNext hat die Mail angelegt und in den Ausgang gestellt | fertig |
| 200, sent: false + grund | Auskunft — es wurde nichts versendet, und warum | umschwenken (anderer Versandweg) |
| 404 / 502 | Störung — Beleg unbekannt, ERPNext nicht erreichbar, PDF kaputt | später erneut versuchen |
Vier Gründe führen zu sent: false:
1. Kein ERPNext-Ausgangskonto — kein Email Account mit
enable_outgoing = 1.
2. Nicht feststellbar, ob eines existiert — z. B. HTTP 403, weil der
API-Nutzer Email Account nicht lesen darf. Wer nicht weiss, ob ERPNext
senden kann, darf nicht so tun, als hätte er gesendet. Der Preis dieser
Strenge steht hier, damit ihn niemand suchen muss: fehlt dieses Leserecht,
sendet das Addon nie, obwohl es könnte — der Grundtext nennt dann genau
den Status, an dem es liegt.
3. Kein Empfänger — weder contact_email noch email_id am Beleg.
4. ERPNext hat den Versand nicht bestätigt — 2xx, aber keine
Communication in der Antwort.
sent: true heisst: **ERPNext hat die Communication angelegt und in die
Ausgangswarteschlange gestellt.** Es heisst nicht, dass der Kunde die Mail
hat — das kann diese Schnittstelle nicht wissen, und sie behauptet es
deshalb auch nicht.
submitIfDraftDefault false (für bestehende Aufrufer ändert sich nichts). Mit true
wird ein Entwurf (docstatus 0) vor dem Versand eingereicht; submitted
in der Antwort sagt, ob das in diesem Aufruf passiert ist. Nur ein echtestrue zählt — die Zeichenkette "true" wird nicht gedeutet, weil
Einreichen eine Mutation ist, die sich nicht rückgängig machen lässt.
Eingereicht wird vor der Mailkonto-Prüfung. Das sieht nach einer
verschwendeten Mutation aus, wenn danach sent: false kommt — ist aber die
richtige Reihenfolge: der Rückfallweg (Versand über den Shop) liest den
gebuchten Beleg. Wer zuerst das Konto prüft und dann das Einreichen
verweigert, macht genau den Weg unmöglich, für den er die Auskunft gibt.
| Methode | Pfad | Zweck | Trust |
| --- | --- | --- | --- |
| GET | /quotation | Beleg suchen — genau ein Schlüssel: ?woocommerceOrderId=… oder ?poNo=…. Kein Treffer ist 200 {gefunden:false}, kein 404 | addons/erpnext/quotation/read |
| POST | /quotation | Entwurf anlegen (docstatus 0), Body {woocommerceOrderId, kunde, kontaktEmail?, kundenAnschrift?, positionen:[{item_code, qty, item_name?, description?, rate?}]}. Gibt es den Beleg schon → 409 quotation_existiert_bereits mit dem vorhandenen Namen | addons/erpnext/quotation/write |
| GET | /quotation/{name} | Beleg lesen (Kunde, Positionen, pdfUrl, erpMailAccount) | addons/erpnext/quotation/read |
| POST | /quotation/{name}/items | Preise je Position, Body {po_no, items:[{name?, item_code?, rate}]} — kein implizites Submit | addons/erpnext/quotation/write |
| POST | /quotation/{name}/comment | Beleg kommentieren, Body {inhalt, autorEmail?, autorName?} — geht auch am gebuchten Beleg | addons/erpnext/quotation/write |
| POST | /quotation/{name}/lost | Verloren markieren mit Grund; Antwort trägt weg (put \\| declare_enquiry_lost) | addons/erpnext/quotation/write |
| GET | /quotation/{name}/pdf | PDF streamen (optional ?format=<Print Format>) | addons/erpnext/quotation/read |
| POST | /quotation/{name}/submit | Submit (docstatus 0→1) | addons/erpnext/quotation/submit |
| GET | /sales-invoice | Gebuchte Rechnung zur Bestellung suchen, ?woocommerceOrderId=… (Filter enthält docstatus = 1) | addons/erpnext/quotation/read |
| POST | /sales-invoice/{name}/quotation-link | Angebotsverweis custom_quotation nachtragen, Body {angebot}; Antwort trägt geschrieben | addons/erpnext/quotation/write |
| POST | /quotation/{name}/send | PDF per E-Mail senden, Body {subject?, message?, format?, submitIfDraft?}, Antwort {sent, grund, submitted, docstatus} | addons/erpnext/quotation/submit |
po_no ist die Bestellnummer, über die die Buchhaltung sucht (#1055).custom_woocommerce_order_id ist der Schlüssel der LayerY-Strecke: n8n-Workflow
01 legt den Entwurf damit an und schreibt kein po_no (gemessen am
12.08.2026 an der aktiven Fassung).
Bis 0.6.1 kannte das Addon nur po_no. Eine Suche nach dem LayerY-Entwurf lief
damit ins Leere und meldete „nicht gefunden" — und wer daraus „also noch keiner
da" schliesst, legt einen zweiten Entwurf für denselben Kunden an. Beide
sehen richtig aus, beide tragen dieselbe Bestellung, und welcher dem Kunden
geschickt wird, entscheidet der Zufall.
Der Riegel gegen den zweiten Beleg sitzt deshalb in POST /quotation selbst und
nicht im Aufrufer. Er ist ein Netz, keine Ausschlussgarantie: zwei Läufer,
die im selben Augenblick suchen, finden beide nichts. Dass nie zwei Läufer
gleichzeitig laufen, ist Sache der Zuteilung (addons#1319) — hier steht es,
damit niemand den Riegel für die Lösung hält.
status trägt an der Quotation allow_on_submit = 0. Ein PUT darauf endet am
gebuchten Beleg (docstatus == 1) in 417. Daraus folgen zwei Dinge:
* lost kennt zwei Wege. Am Entwurf bleibt es beim Voll-Doc-PUT (in
Betrieb, füllt lost_reasons). Am gebuchten Beleg geht es über
run_doc_method/declare_enquiry_lost — die Methode schreibt per db_set
und umgeht die Sperre. n8n-Workflow 03 macht es seit jeher so und begründet
es im Knoten „Status abbilden". Welcher Weg gegangen wurde, steht im Feld
weg der Antwort, damit niemand rekonstruieren muss, warum lost_reasons
einmal gefüllt ist und einmal nicht.
* Ein Kommentar ist der einzige verbleibende Vermerk. Deshalb gibt es
/comment. Ein abgelehntes declare_enquiry_lost (z. B. Angebot bereits
„Ordered") wird gemeldet und geht nie als Erfolg durch — sonst gälte eine
Absage als verbucht, die nie ankam.
ERPNext kennt die Kette Angebot → Auftrag → Rechnung. Bei LayerY entsteht die
Rechnung aber direkt aus der Shop-Bestellung, weil der bestehende
Bestell-Sync das seit jeher so macht — samt Zahlungseingang und
Anbietergebühr. Eine zusätzliche Rechnung aus dem Angebot heraus wäre eine
Doppelbuchung. Deshalb verbindet quotation-link nur, was ohnehin schon
da ist. (Die Begründung steht als Sticky Note auch in n8n-Workflow 04.)
Drei Fälle, drei Antworten, keiner davon still:
\n| Zustand an der Rechnung | Antwort |
| --- | --- |
| custom_quotation leer | schreiben, geschrieben: true |
| schon derselbe Verweis | nichts tun, geschrieben: false — ein Treffer, kein Fehler |
| ein anderer Verweis | 409 verweis_zeigt_woandershin, nichts wird überschrieben |
Der zweite Fall ist kein Luxus: Workflow 04 läuft alle 15 Minuten über
dieselbe Bestellliste. Der dritte ist der teure — ein überschriebener Verweis
sähe hinterher aus wie ein richtiger, und welche Zuordnung die gewollte war,
liesse sich nicht mehr rekonstruieren.
Geschrieben wird nur dieses eine Feld, nie das ganze Doc: die Rechnung ist
gebucht, ein Voll-Doc-PUT liefe in dieselbe allow_on_submit-Sperre wie beilost (addons#1317).
Das sind alle Routen des Addons — je eine Zeile je route.ts untersrc/app/api/v1/addons/erpnext/. Gemessen an origin/develop: sechsroute.ts, alle unter quotation/ (Einzahl).
Es gibt keine zweite Pfadfamilie: /quotations/… (mit s) hat nie
existiert — git ls-tree findet dafuer null Dateien. Die Zeilen dafuer standen
bis addons#1221 hier, samt der Bezeichnung „Alias" fuer die einzigen echten
Routen. Wer danach debuggt hat, suchte eine 404, die das Addon nie vorgesehen
hat.
AIOPTA_CONFIG_BASEURL → ERPNext-Basis-URL (kein Default)AIOPTA_CREDENTIAL_APITOKEN → api_key:api_secret (nie als Argument)Slots werden vom Core injiziert; ohne aufgelösten apiToken oder ohne
aufgelöste baseUrl fails jedes Tool CLOSED mit „nicht konfiguriert" (nie
erfundene Daten, und kein Netzruf an einen geratenen Wirt). Handshake undtools/list funktionieren weiterhin ohne jede Env.
Zwei Familien, und sie sind nicht dasselbe (addons#1187):
\nDie Routen hängen an den quotation-eigenen Rechten auscapabilityDeclarations[] — die Slash-Form der jeweiligen Capability:
addons/erpnext/quotation/read — Quotations lesen, PDF, PDF-URL.addons/erpnext/quotation/write — Preise setzen (docstatus bleibt 0), Verloren mit Grund.addons/erpnext/quotation/submit — Submit (docstatus 0→1), E-Mail-Versand.Die Skills und der MCP-Server führen die gröberen Addon-Rechte:
\naddons/erpnext/read — Skill erpnext-read, MCP-Tools (read-only).addons/erpnext/write — Skill erpnext-write.addons/erpnext/submit — Skill erpnext-submit.Die Durchsetzung für Agent-API-Keys erfolgt core-seitig (Agent-Scope-
Enforcement anhand der deklarierten Permissions).
A file hosting service addon for Aiopta that provides file upload, download, and public URL generation capabilities using Aiopta's Next.js API routes.
\n{\n "publicUrl": "http://localhost:3000",\n "requireToken": true,\n "uploadDir": "data/uploads",\n "maxFileSize": 104857600,\n "allowedMimeTypes": [\n "image/jpeg",\n "image/png",\n "image/gif",\n "image/webp",\n "application/pdf",\n "text/plain",\n "text/markdown",\n "application/json",\n "application/zip",\n "application/x-zip-compressed"\n ]\n}| Option | Type | Default | Description |
|--------|------|---------|-------------|
| publicUrl | string | "http://localhost:3000" | The public base URL for file access |
| requireToken | boolean | true | Whether authentication is required |
| uploadDir | string | "data/uploads" | Directory to store uploaded files |
| maxFileSize | number | 104857600 (100MB) | Maximum file size in bytes |
| allowedMimeTypes | string[] | See default | List of allowed MIME types |
### Upload File
POST /api/v1/addons/file-hosting/upload
Upload a file and get its ID and public URL.
### Get File Info
GET /api/v1/addons/file-hosting/file/:id
Get file metadata and download URL.
### Download File
GET /api/v1/addons/file-hosting/serve/:id?token={apiKey}
Download the file. Token can be provided via query param, Authorization header, or X-API-Key header.
### Delete File
DELETE /api/v1/addons/file-hosting/file/:id
Delete a file by ID.
### Get Configuration
GET /api/v1/addons/file-hosting/config
Get the current addon configuration.
### Update Configuration
POST /api/v1/addons/file-hosting/config
Update the addon configuration.
Upload:
```bash
curl -X POST http://localhost:3000/api/v1/addons/file-hosting/upload \\
-F "file=@document.pdf"
```
Download with token:
```bash
curl "http://localhost:3000/api/v1/addons/file-hosting/serve/{id}?token={your_api_key}" -o file.pdf
```
This addon uses Aiopta's Next.js web server for all file serving operations. No standalone server is required.
\nWhen requireToken: true, files can only be accessed with valid authentication:
1. Query Parameter: ?token={apiKey}
2. Authorization Header: Authorization: Bearer {apiKey}
3. X-API-Key Header: X-API-Key: {apiKey}
The token must be a valid Aiopta API key.
", "byteSize": 3187 } } }, { "id": "forgejo", "uuid": "1e4f363b-6556-4e35-b5e4-9500c03082ea", "name": "Forgejo", "version": "1.2.4", "description": "Manage Forgejo / Gitea instances from Aiopta: list repositories, issues, pull requests, projects, milestones, releases, and labels through a single dashboard, plus a per-user instance picker for admins and end-users. Slice #227 ships the skeleton (manifest + page shell + SKILL.md placeholder). Slice #228 ships the typed HTTP client with token-redaction and retry semantics. Slice #229 ships the instance picker (admin + user, AES-GCM at-rest token encryption, per-user isolation, connectivity test, empty-state CTA — no defaults). Slice #230 ships the read-dashboard (filter engine, priority mapper, LRU cache with stampede protection, and the API routes + UI components for repos/issues/PRs tabs). Slice #231 ships the Issue/PR write API on top of the read dashboard (CRUD, comments, labels, reviews, merge, approval gate, idempotency, job pattern). Projects CRUD in #232, SKILL.md freeze in #233.", "author": "Aiopta", "icon": "🦊", "capabilities": [ "forgejo", "gitea", "repositories", "issues", "pull-requests", "projects", "milestones", "releases", "labels" ], "tags": [], "download": "/artifacts/forgejo-1.2.4.zip", "sha256": "4742b3e634ea274f3630cba6a5c40d9af88aa15a7eea644c9ab10ddbd27f50c5", "size": 917022, "page": [ { "id": "forgejo", "path": "/addons/forgejo", "name": "Forgejo", "icon": "🦊", "section": "Dev", "component": "@addons/forgejo/src/components/ForgejoDashboard" } ], "deprecated": false, "endpoints": [ "/api/v1/addons/forgejo/repos", "/api/v1/addons/forgejo/issues", "/api/v1/addons/forgejo/pulls", "/api/v1/addons/forgejo/projects", "/api/v1/addons/forgejo/labels", "/api/v1/addons/forgejo/members", "/api/v1/addons/forgejo/cache/stats", "/api/v1/addons/forgejo/issues/{instance}/{repo}", "/api/v1/addons/forgejo/issues/{instance}/{repo}/{index}", "/api/v1/addons/forgejo/issues/{instance}/{repo}/{index}/state", "/api/v1/addons/forgejo/issues/{instance}/{repo}/{index}/comments", "/api/v1/addons/forgejo/issues/{instance}/{repo}/{index}/labels", "/api/v1/addons/forgejo/issues/{instance}/{repo}/{index}/assignees", "/api/v1/addons/forgejo/issues/bulk/label", "/api/v1/addons/forgejo/pulls/{instance}/{repo}/{index}", "/api/v1/addons/forgejo/pulls/{instance}/{repo}/{index}/files", "/api/v1/addons/forgejo/pulls/{instance}/{repo}/{index}/commits", "/api/v1/addons/forgejo/pulls/{instance}/{repo}/{index}/reviews", "/api/v1/addons/forgejo/pulls/{instance}/{repo}/{index}/merge", "/api/v1/addons/forgejo/pulls/{instance}/{repo}/{index}/state", "/api/v1/addons/forgejo/jobs/{id}", "/api/v1/addons/forgejo/instances", "/api/v1/addons/forgejo/instances/{id}", "/api/v1/addons/forgejo/instances/{id}/test", "/api/v1/addons/forgejo/admin/instances", "/api/v1/addons/forgejo/admin/instances/{id}" ], "skills": [], "mcpServers": [ { "id": "forgejo-tools", "displayName": "Forgejo tools", "description": "Read-only Forgejo/Gitea companion tools for agents: decode/encode the dashboard issue/PR filter wire format, map priorities to label names, detect issue priority, redact credential patterns from text, and validate instance base URLs and labels - faithful ports of the addon's src/lib modules (issue #420, epic #399). Mutates nothing; live per-user Forgejo access is resolved core-side via the declared config/credential slots.", "transport": "stdio", "runtime": "node", "entry": "forgejo-tools/server.mjs", "permissions": [ "addons/forgejo/read" ], "toolPolicy": { "mode": "read-only", "allowDestructive": false }, "configRefs": [ "baseUrl" ], "credentialRefs": [ "token" ], "archiveEntry": "forgejo/mcp/servers/forgejo-tools/server.mjs", "sha256": "8f479e5a96d349cd12582a4f026721f1e5c27941808fe59971a1d3097500cbc4", "size": 29917, "descriptorVersion": 1 } ], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "Aiopta integration for Forgejo and Gitea. Manage repositories,
issues, pull requests, projects, milestones, releases, and labels
across one or more Forgejo / Gitea instances — both from the dashboard
UI (/addons/forgejo) and through the Aiopta agent skill
(SKILL.md).
\nStatus: 1.0.0. Slices #227 (skeleton), #228 (typed client +
token-redaction + retry), and #230 (read-dashboard: filter engine,
priority mapper, LRU cache with stampede protection, API routes, and
UI components) are landed. Slice #233 (SKILL.md + agent discovery
smoke + README polish) is finalising the agent-surface + the
1.0.0 manifest. Instance picker (#229), write API (#231), and
projects / milestones / releases / labels admin (#232) are tracked
as separate issues — see the Roadmap below.
- Addon ID: forgejo
- Version: 1.0.0 (slice #228 client + slice #230 read-dashboard
+ slice #233 SKILL.md agent surface)
- Capabilities: forgejo, gitea, repositories, issues,
pull-requests, projects, milestones, releases, labels
- UI Page: /addons/forgejo
- Author: Aiopta
- License: Per the surrounding Aiopta addon marketplace terms
Forgejo's HTTP API is API-compatible with Gitea's. A single client
serves both — no parallel code path. The addon assumes upstream
versions >= Forgejo 1.20 / Gitea 1.20; older instances will receive
a 426 Upgrade Required response from the concrete endpoints (seeforgejo-client.ts).
| Issue | Title | Status | Slice |
|---|---|---|---|
| #227 | Forgejo-Addon skeleton | ✅ | manifest, page shell, docs |
| #228 | TypeScript client + auth wrapper (token redaction, retry) | ✅ | core client |
| #229 | Instance management (admin + user, scoped storage, RBAC, encrypted tokens) | ⏳ | instance picker |
| #230 | Read dashboard with repos/issues/PRs + filter engine | ✅ | dashboard backend + UI |
| #231 | Issue/PR detail + write API (CRUD, comments, labels, reviews, merge, approval gate) | ⏳ | write surface |
| #232 | Projects + milestones + releases + labels admin | ⏳ | board surface |
| #233 | SKILL.md + agent discovery smoke + README polish | ✅ | agent surface (this slice) |
The Forgejo addon does not require any environment variables at
install time. The HTTP client is instantiated lazily when the user
configures a per-user instance (slice #229 lands the instance picker
and the encrypted-token storage). Until then, an env-var-backed
default instance store lets the dashboard run against a single
configured instance.
Runtime data that the addon needs to operate:
\n| Source | Where it lives | Notes |
|--------|----------------|-------|
| Per-user instance URL | caller's per-user data root (<DATA_DIR>/addons/forgejo/<userId>/instances.json) | Configured via the dashboard. No hardcoded default. |
| Per-user access token | same root, encrypted at rest | Slice #229. |
| Upstream Forgejo / Gitea version | n/a | Required >= 1.20. Older versions emit 426 Upgrade Required. |
For the env-var-backed default instance store, set:
\nexport FORGEJO_INSTANCE_<ID>_URL="https://your-forgejo-host.example"\nexport FORGEJO_INSTANCE_<ID>_TOKEN="ghp_…"\n# Optional: override the priority label prefix (default: "priority:")\nexport FORGEJO_PRIORITY_PREFIX="prio"\n# Optional: override the read-cache TTL (default: 60s)\nexport FORGEJO_READ_CACHE_TTL_SECONDS=120Slice #229 will replace the env-var backend with a DB-backed store
without changing the instance-store.ts interface.
The agent skill (SKILL.md) is the canonical endpoint cheat-sheet
for the agent. The manifest's endpoints array mirrors the slice
#228 baseline of the typed client — every endpoint listed there is
reachable from @addons/forgejo/src/lib/forgejo-client.ts today.
The slice #230 read-dashboard exposes an additional Aiopta-side
aggregation surface under /api/v1/addons/forgejo/*.
| Resource | Paths |
|----------|-------|
| User | /user, /user/repos, /user/projects |
| Repos | /repos/{owner}/{name} |
| Issues | /repos/{repo}/issues, /repos/{repo}/issues/{number}, /repos/{repo}/issues/{number}/comments |
| Pulls | /repos/{repo}/pulls, /repos/{repo}/pulls/{number} |
| Projects | /repos/{repo}/projects, /user/projects |
| Milestones | /repos/{repo}/milestones |
| Releases | /repos/{repo}/releases |
| Labels | /repos/{repo}/labels |
| Method | Path | Purpose |
| ------ | ---- | ------- |
| GET | /api/v1/addons/forgejo/repos?instance=&search= | List repos for the active instance |
| GET | /api/v1/addons/forgejo/issues?<filter> | List issues for a repo |
| GET | /api/v1/addons/forgejo/pulls?<filter> | List PRs for a repo |
| GET | /api/v1/addons/forgejo/projects?instance=&repo= | Project boards |
| GET | /api/v1/addons/forgejo/labels?instance=&repo= | Repo labels (filter dropdown source) |
| GET | /api/v1/addons/forgejo/members?instance=&org= | Org members (author / assignee source) |
| GET | /api/v1/addons/forgejo/cache/stats | Cache diagnostic counts |
Future slices extend this surface:
\n- #229 — per-user instance picker (local-only routes, no new
upstream endpoints)
- #231 — write API + approval gate (consumes the slice #228
create / update / addComment endpoints; adds
POST /repos/{repo}/pulls/{number}/merge)
- #232 — projects / milestones / releases / labels admin (adds
POST /user/projects, PATCH /projects/{id}, and label CRUD
against /repos/{repo}/labels)
addons/forgejo/src/lib/)- issue-filters.ts — typed IssueFilter + URL codec.
Multi-value groups use repeated keys (?labels=bug&labels=urgent)
so labels containing commas, colons, or Unicode roundtrip
unambiguously. AND across groups, OR within each group.
Defaults: state=open, limit=50 (hard cap 200).
- priority-mapper.ts — maps priority values to label names with
a configurable prefix (default priority:). Accepts compact
P0..P3 aliases. Detects the highest priority present on an
issue's labels via detect().
- read-cache.ts — per-user LRU cache with TTL (default 60s,
overridable via FORGEJO_READ_CACHE_TTL_SECONDS) + stale-while-
revalidate + stampede protection (100 concurrent identical
requests coalesce into one upstream call). Cache keys NEVER
contain the configured token; user-supplied free-text q is
FNV-1a-hashed before key assembly.
- instance-store.ts — read-side contract for the per-user
instance + token lookup. Ships an env-var-backed default so the
dashboard runs before slice #229's DB schema lands; the
implementation in #229 swaps the loader while keeping the
interface intact.
- read-dashboard-api.ts — server-side helpers used by every
read route: instance resolution, typed client construction, the
shared read cache, and the DashboardError wire shape (code /
lastSuccessAt / retryAfterMs).
addons/forgejo/src/app/api/v1/addons/forgejo/)- GET /repos?instance=&search=&page=&limit= — list repos for the
active instance.
- GET /issues?<filter> — list issues for a repo, filtered.
- GET /pulls?<filter> — list PRs for a repo, filtered.
- GET /projects?instance=&repo= — project boards.
- GET /labels?instance=&repo= — repo labels (filter dropdown
source).
- GET /members?instance=&org= — org members (author / assignee
typeahead).
- GET /cache/stats — diagnostic cache stats (size / hits / misses
/ stampedeHits / evictions / hit-ratio).
All routes are userRoute-wrapped (auth required) and flow through
the shared cache + stampede helper.
addons/forgejo/src/components/ + hooks/)- ForgejoDashboard.tsx — three-tab page (Repos / Issues / PRs)
with instance + repo pickers. Filter state is mirrored to the URL
via useForgejoQuery so refresh restores the exact view and the
browser back/forward buttons navigate between filter histories.
- IssueFilterBar.tsx / PRFilterBar.tsx — combined filter
bars (labels, priority, state, author, assignee, updated-range,
full-text q).
- IssueTable.tsx / PRTable.tsx / ReposTable.tsx —
tables with cursor-style pagination (50 default, 200 hard cap, no
endless scroll in v1).
- LabelPill.tsx / PriorityPill.tsx — coloured chips with
stable priority colour mapping (critical=red, high=orange,
medium=yellow, low=gray).
- EmptyState.tsx — three distinguished copy variants:
no_matches, repo_empty, no_instance — each with its own
data-i18n-key for the v1 localisation wire.
- ErrorState.tsx — stable code / lastSuccessAt /
retryAfterMs UX with a Retry button on transient errors and a
"Renew token" CTA on UNAUTHORIZED.
- StaleDataBanner.tsx — "Data from X — stale by Ys" banner
when the cache TTL has elapsed (stale-while-revalidate).
- useForgejoQuery — data-fetching hook with URL sync,
background revalidation, and typed error surface.
- tests/unit/issue-filters.test.ts (52 tests) — Encode/Decode
roundtrip + 20 random vectors + special-character handling +
pagination caps.
- tests/unit/priority-mapper.test.ts (21 tests) — default prefix
+ custom prefix (prio → prio:high) + aliases + detection.
- tests/unit/read-cache.test.ts (20 tests) — TTL, stampede
protection (100 calls → 1 upstream), token redaction invariant,
LRU eviction, per-user isolation.
- tests/unit/read-api.test.ts (12 tests) — integration coverage
for every read endpoint against the mock Forgejo server +
DashboardError shape + stampede.
- tests/e2e/dashboard.spec.ts — Playwright spec covering tab
navigation, three-filter combination + URL roundtrip + back-button
restoration, empty-state rendering, and upstream error UX.
- Typed HTTP client. src/lib/forgejo-client.ts wraps the
upstream REST API in a small typed surface (repos, issues,
pulls, projects, milestones, releases, labels,
users). It uses Node 20+ built-in fetch + AbortController
— no gitea-js or undici dependency (see
docs/LIBRARY-EVALUATION.md for the rationale).
- Token redaction. src/lib/token-redaction.ts rewrites every
token <value> and Bearer <value> literal to ***REDACTED***
in response bodies, error messages, and stack traces before they
leave the client. The unit test
tests/unit/token-redaction.test.ts pins this contract.
- Retry semantics. src/lib/retry.ts implements exponential
backoff (baseMs, doubling per attempt), honours the upstream
Retry-After header on 429, and stops at maxRetries (default
3). Retryable codes are 429 and any 5xx; non-retryable 4xx
propagate immediately.
- Per-user isolation. Every persisted artifact is registered via
registerScopedTable() per ADR-054. The addon never reads or
writes another user's instance configuration or cached state.
- No hardcoded default instance. No demo URL, no demo token, no
silent default admin. When the user has not configured an
instance, the dashboard shows an empty state with a CTA and every
API call returns a clear instance_not_configured error (slice
#229 will codify that error code).
- Approval gate. Write operations (issue close, PR merge, label
changes) flow through the existing autonomy/approval pipeline —
never silently executed. The read-dashboard does not perform any
writes.
- addons/forgejo/SKILL.md — the agent skill, with the 5 mandatory
sections (Purpose, When to use, Capability / security, Endpoint
cheat-sheet, Example curl) modelled on
addons/task-board/SKILL.md.
- addons/forgejo/README.md — this file (Setup, Env-Vars, Endpoint
overview, Architecture notes).
- addons/forgejo/addon.json — finalised manifest with
version: 1.0.0, the complete endpoints list (slice #228 typed
client baseline + slice #230 read-dashboard routes),
capabilities, and pages array.
- addons/forgejo/tests/integration/skill-discovery.test.ts —
agent-discovery smoke test: stub loader finds SKILL.md and
parses the 5 sections successfully.
- addons/forgejo/tests/integration/marketplace-build.test.ts —
confirms npm run build:artifacts produces a ZIP and
npm run build:catalog includes the entry.
- No new HTTP endpoints — this slice is docs + tests only.
- No new client methods — slice #228 owns the client surface.
- No instance picker — slice #229.
- No filter engine — slice #230.
- No write operations — slices #231 / #232.
- No agent-loader changes — the loader lives in
aiopta-core/src/lib/addons/addon-skills.ts and is out of scope
for this slice.
Per the Aiopta addon marketplace repository terms.
", "byteSize": 13228 } } }, { "id": "hermes-desktop", "uuid": "332ed156-aa4b-4dd4-92b7-fd173b48d71f", "name": "Hermes Desktop", "version": "0.6.3", "description": "Commit-pinned feature matrix for NousResearch hermes-agent desktop capabilities plus a secret-free capability adapter (issues #101 + #169), a per-user Hermes sessions UI (sessions list, SSE stream with chunk dedupe, Stop, Retry — issue #120), a per-user workspace file browser + sandboxed preview envelope (issue #167), a secret-free settings panel for model / personality / skills / memory / automation-status (issue #121), an optional voice input / output panel with explicit opt-in, retention hints and secret-free verdict (issue #168), and a pinned upstream + image-compatibility contract (issue #169). The shell surfaces only capabilities and settings backed by an Aiopta contract — no optimistic flags. Status: chat-streaming/tool-activity/sessions/provider/personality/skills/memory/automation/tool-settings are partial, file-browser/side-by-side-previews are partial (issue #167 — capability-gated, per-user workspace root, sandboxed preview, no core-origin rights for active content), voice-input + voice-output are partial (issue #168 — explicit opt-in, secret-free, retention hint, no audio bytes logged, permission revoke collapses to unavailable), image-pin is partial, upstream-update is unsupported-by-design, shell-cache-invalidation/shell-no-optimistic-flags/preview-sandbox/no-file-url/voice-secret-free are full. Pin JSON (hermes-desktop.pin.json) hard-binds the source commit + the OCI image + sha256 imageDigest + API schema version + license + compatibility issue per issue #169; any drift is a hard error in scripts/validate-addons.cjs. The browser talks only to Aiopta APIs — no Hermes-domain code is duplicated here.", "author": "Aiopta", "icon": "📜", "capabilities": [ "hermes-desktop", "feature-matrix", "capability-adapter", "secret-free-status", "commit-pinned-contract", "image-digest-pinned", "api-schema-version-pinned", "supply-chain-checked", "hermes-sessions", "hermes-streaming", "hermes-stream-stop", "hermes-stream-retry", "hermes-workspace-files", "hermes-workspace-preview", "preview-sandboxed", "no-file-url", "settings-panel", "settings-shell-state", "voice-input", "voice-output", "voice-opt-in", "voice-secret-free", "voice-audio-size-limit" ], "tags": [], "download": "/artifacts/hermes-desktop-0.6.3.zip", "sha256": "e0cf77980569d5be82f2fdba6291601cbfd1c884a8c5bd92fff4b6b74a8ac87c", "size": 928997, "page": { "id": "hermes-desktop", "name": "Hermes Desktop", "path": "/addons/hermes-desktop", "icon": "📜", "section": "Tools", "component": "@addons/hermes-desktop/src/components/HermesDesktopPage" }, "deprecated": false, "endpoints": [ "/api/v1/addons/hermes-desktop/capabilities", "/api/v1/addons/hermes-desktop/sessions", "/api/v1/addons/hermes-desktop/sessions/{id}/stream", "/api/v1/addons/hermes-desktop/sessions/{id}/stop", "/api/v1/addons/hermes-desktop/sessions/{id}/retry", "/api/v1/addons/hermes-desktop/files", "/api/v1/addons/hermes-desktop/preview", "/api/v1/addons/hermes-desktop/settings", "/api/v1/addons/hermes-desktop/voice" ], "skills": [ { "name": "hermes-desktop-capabilities", "displayName": "Hermes Desktop: Capability Matrix", "description": "Read the commit-pinned Hermes-desktop feature matrix and the live capability-adapter verdict for the current backend driver. Secret-free: the route returns status + a reference to the upstream row, never credentials. Use this skill to answer 'which Hermes features work in Aiopta right now?' — no live Hermes call required.", "permissions": [ "addons/hermes-desktop/capabilities" ], "endpoint": "/api/v1/addons/hermes-desktop/capabilities", "scripts": [ { "id": "hermes-desktop-capabilities-cli", "name": "hermes-desktop-capabilities-cli", "path": "hermes-desktop-capabilities/cli.sh", "sha256": "a377bf88125a933c465d28ef61d631c5c7bc8742a7466ea7af7dedfe3e4844fb", "interpreter": "bash", "timeoutMs": 10000, "permissions": [ "addons/hermes-desktop/capabilities" ], "inputSchema": { "type": "object", "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "timeoutMs": { "type": "integer", "minimum": 100, "maximum": 300000 } } }, "outputSchema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "integer" }, "data": {}, "error": { "type": "string" }, "truncated": { "type": "boolean" } } }, "size": 12176 } ] }, { "name": "hermes-desktop-sessions", "displayName": "Hermes Desktop: Per-User Sessions", "description": "Read the per-user Hermes sessions list, stream chunks, and Stop/Retry an in-flight session (issue #120). The route is per-user, capability-flagged, and secret-free. No live Hermes call is made — the page renders the cached chat-addon session list and surfaces the HermesDesktop capability verdict for the page to gate Stop/Retry buttons.", "permissions": [ "addons/hermes-desktop/sessions", "addons/hermes-desktop/sessions/{id}/stream", "addons/hermes-desktop/sessions/{id}/stop", "addons/hermes-desktop/sessions/{id}/retry" ], "endpoint": "/api/v1/addons/hermes-desktop/sessions", "scripts": [] }, { "name": "hermes-desktop-workspace", "displayName": "Hermes Desktop: Workspace Files & Preview", "description": "Read a per-user workspace file listing and a sandboxed preview of a single file (issue #167). The endpoints are per-user (each user sees their own workspace root, never another user's), capability-gated, and secret-free. Previews are returned as envelopes (mime + body + sandbox + CSP) — never as `file://` URLs or raw paths. Active content in HTML / PDF previews is sandboxed (no `allow-same-origin`) so it cannot reach the core origin.", "permissions": [ "addons/hermes-desktop/files", "addons/hermes-desktop/preview" ], "endpoint": "/api/v1/addons/hermes-desktop/files", "scripts": [] }, { "name": "hermes-desktop-settings", "displayName": "Hermes Desktop: Settings Panel", "description": "Read the per-row settings verdict for the matrix rows whose group is 'settings' (model / personality / skills / memory / automation-status). Secret-free: the route returns supported/unsupported/unreachable + the Aiopta route that owns the value + the recency of the last successful observation + a stable error code, never credentials or setting values. Use this skill to answer 'which Hermes settings can the user act on right now?' — no live Hermes call required.", "permissions": [ "addons/hermes-desktop/settings" ], "endpoint": "/api/v1/addons/hermes-desktop/settings", "scripts": [] }, { "name": "hermes-desktop-voice", "displayName": "Hermes Desktop: Voice Input / Output", "description": "Read the per-row voice verdict (voice-input / voice-output) for the matrix rows whose id starts with 'feat-voice-'. Secret-free: the route returns the per-row shell state (ready | degraded | unavailable | unsupported) + the provider id (NEVER the URL or credential) + the stable error code + the retention hint (max audio bytes, transcript preview limit) — never audio bytes, transcripts, or backend credentials. The verdict is consent-aware: until the user explicitly opts in, every row reports CONSENT_REQUIRED. The agent must surface the verdict verbatim and never recommend a default opt-in.", "permissions": [ "addons/hermes-desktop/voice" ], "endpoint": "/api/v1/addons/hermes-desktop/voice", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "This addon ships the pinned-upstream + image-compatibility contract
for the NousResearch hermes-agent
desktop capabilities together with a secret-free capability adapter
that tells the Aiopta shell which Hermes features are usable right now
on the active backend driver, a per-user Hermes sessions UI
(session list, SSE stream with chunk dedupe, Stop, Retry — issue #120),
a per-user workspace file browser + sandboxed preview envelope
(issue #167), a secret-free settings panel that surfaces the
5 settings-group rows of the matrix (model / personality / skills /
memory / automation-status — issue #121) with a dedicated
shell-state vocabulary (supported | unsupported | unreachable) plus
the recency of the last successful observation and a stable error
code, and an optional voice input/output panel with explicit
opt-in, secret-free verdict, retention hints and a 10 MiB audio size
limit (issue #168). The browser talks only to Aiopta APIs — no
Hermes-domain code is duplicated here.
| Property | Value |
|----------|-------|
| Addon id | hermes-desktop |
| Matrix source | hermes-desktop-parity.json (16 rows, pinned) |
| Pin file | hermes-desktop.pin.json |
| Pin commit | ea8a8b4af8612b655a5bbfc74eba21e1e806758d |
| Pin image | nousresearch/hermes-agent |
| Pin image digest | sha256:dabcf559…a7cb — PLACEHOLDER (sha256 sentinel, no latest); real immutable digest pending, see issue #169 caveat below |
| Pin API schema version | 1.0.0 (Semver) |
| Pin license | MIT |
| Spec issue | #101 |
| Compatibility issue | #169 (pinned upstream + image-compatibility contract) |
| Follow-ups | #120 (sessions UI, done in 0.2.0), #121 (settings panel, done in 0.2.0), #167, #168 |
| Endpoints | GET /api/v1/addons/hermes-desktop/capabilities (issue #101)<br>GET /api/v1/addons/hermes-desktop/sessions (issue #120, per-user slice)<br>GET /api/v1/addons/hermes-desktop/sessions/{id}/stream (SSE with chunk dedupe)<br>POST /api/v1/addons/hermes-desktop/sessions/{id}/stop (capability-gated)<br>POST /api/v1/addons/hermes-desktop/sessions/{id}/retry (capability-gated)<br>GET /api/v1/addons/hermes-desktop/settings (issue #121, secret-free per-row verdict) |
| Pages | /addons/hermes-desktop (matrix + settings panel, #101 + #121)<br>/addons/hermes-desktop/sessions (sessions list + stream pane, #120) |
| Secrets / tokens | none — adapter + sessions routes + settings route return status + references, never credentials or setting values |
| Hard-coded URLs | none — paths come from the matrix JSON + the settings source-bindings map |
| unsupported | upstream self-update is intentionally unsupported (by design) |
hermes-desktop.pin.json is the single source of truth for the contract
that binds Hermes-desktop to upstream. The contract is explicit,
rollback-capable, and supply-chain-checked:
| Field | Purpose |
|-------|---------|
| commit | Pinned git source commit (issue #101) |
| image | OCI registry/repository reference (e.g. nousresearch/hermes-agent) |
| imageDigest | sha256-pinned image digest — ^sha256:[a-f0-9]{64}$, no latest |
| apiSchemaVersion | Pinned Semver of the upstream API contract |
| license | Upstream license string, stored alongside the rest of the contract |
| compatibilityIssue | Reference to the contract that hardens the pin (issue #169) |
The matrix JSON (hermes-desktop-parity.json) mirrors every field
above in its pin block. Drift between the two files is a hard error
from scripts/validate-addons.cjs (issue #101 + #169) and from the
runtime matrix loader (src/lib/matrix.ts:validateMatrix).
The adapter (src/lib/capability-adapter.ts) surfaces the full contract
in the verdict and degrades rows to down / unsupported-version
when the running image's sha256 digest or the backend's API schema
version drifts from the pin — never an optimistic full flag.
Update procedure (explicit, rollbackable, supply-chain checked):
1. Operator decides to bump: change all four pinned fields in
hermes-desktop.pin.json AND in hermes-desktop-parity.json
(pin block) in a single PR.
2. scripts/validate-addons.sh hard-fails on any drift between the
two JSONs.
3. node --test addons/hermes-desktop/tests/unit/pin.test.cjs
covers the schema contract for new fields.
4. Rollback: git revert the PR — pin, matrix, and matrix rows move
together, so a single revert restores the prior contract.
5. Supply-chain check: the imageDigest field is sha256-pinned and the
adapter reports imageDigestOk=false if the running image's sha256
does NOT match. No latest tag, no silent fallback.
The real immutable sha256 digest of nousresearch/hermes-agent at the
pinned commit is not yet available in issue #169. To keep the
contract shape enforced end-to-end (drift detection betweenhermes-desktop.pin.json, the matrix pin block, and theHERMES_DESKTOP_PIN_IMAGE_DIGEST constant in scripts/validate-addons.cjs
all work) without faking a real digest, the three mirrors currently carry
a clearly-nonzero placeholder digest — the sha256 of a descriptive
sentinel string. It passes the ^sha256:[a-f0-9]{64}$ shape check but
is not a real image digest.
Before this addon is trusted for production supply-chain claims, an
operator must replace the placeholder in all three mirrors with the
actual docker digest (or registry manifest digest) of the pinned image.
Until then the feat-image-pin matrix row is partial, not full.
hermes-agent ships a desktop client with a broad feature surface
(streaming, sessions, side-by-side previews, file browser, voice, settings,
updates). Aiopta already covers the chat / streaming / sessions / settings
paths through other addons (chat, development, memories, skills).
The risk is that the Aiopta browser ends up duplicating Hermes-domain code,
or worse, advertising features that are not actually wired up.
This addon fixes that:
\n1. The matrix (hermes-desktop-parity.json) is the only source of
truth for "which Hermes feature exists in Aiopta, where, and at what
coverage level". Each row binds an upstream feature to an Aiopta
contract (capability + route + skill + UI + test) and tags it
full | partial | missing | unsupported | different. Rows tagged
with group: "settings" (issue #121) are rendered together in the
settings panel.
2. The capability adapter (src/lib/capability-adapter.ts) reads
the matrix and returns the shell-verified state (`not-selected |
down | old | unsupported | full`) for every row, keyed by the
active backend driver. The cache invalidates on backend switch —
there are no optimistic "ready" badges.
3. The settings adapter (src/lib/settings-adapter.ts) reads the
matrix rows whose group === "settings" and returns a per-row
settings verdict (supported | unsupported | unreachable) plus the
last-refreshed timestamp and the stable error code. The verdict is
keyed by (backend, live-state-hash) so a backend switch OR a
change in the live Aiopta configuration source forces a fresh
evaluation.
4. The shell (src/components/HermesDesktopPage.tsx) renders only
what the capability adapter actually returned. The settings panel
(src/components/SettingsPanel.tsx) renders only what the settings
adapter returned. Missing/unsupported/down/unreachable rows are
labelled honestly. The user never sees "voice input: ready" when
the upstream contract is missing, nor "memory: supported" when
the memories addon is unreachable.
| File | Purpose |
|------|---------|
| hermes-desktop.pin.json | Frozen commit SHA + spec/parity issue refs |
| hermes-desktop-parity.json | 20-row feature matrix (validated by validate-addons.cjs) |
| hermes-desktop-parity.schema.json | JSON Schema for the matrix (draft-07) |
| addon.json | Aiopta manifest (capability list, endpoints, page) |
| src/manifest.ts | Runtime extension manifest (ADR-001 dual-registration) |
| src/page.ts | Page descriptor consumed by the registry generator |
| src/components/HermesDesktopPage.tsx | Shell — renders the capability matrix + the settings panel + the voice panel |
| src/components/SettingsPanel.tsx | Settings panel — model / personality / skills / memory / automation (issue #121) |
| src/components/VoicePanel.tsx | Voice input/output panel — explicit opt-in, secret-free, retention hint, audio size limit (issue #168) |
| src/app/api/v1/addons/hermes-desktop/capabilities/route.ts | Capability-adapter endpoint (secret-free, authenticated) |
| src/app/api/v1/addons/hermes-desktop/settings/route.ts | Settings-adapter endpoint (secret-free, authenticated, issue #121) |
| src/app/api/v1/addons/hermes-desktop/voice/route.ts | Voice-panel endpoint (secret-free, authenticated, issue #168): per-row voice verdict + retention hint |
| src/lib/matrix.ts | Matrix loader + validator (pure) — accepts the optional group field (issue #121) |
| src/lib/capability-adapter.ts | Capability-adapter logic — backend-aware, cache-aware, secret-free (pure) |
| src/lib/settings-adapter.ts | Settings-adapter logic — backend- + live-state-aware, cache-aware, secret-free (pure, issue #121) |
| src/lib/voice-adapter.ts | Voice-adapter logic — backend- + live-snapshot-aware, consent-aware, cache-aware, secret-free (pure, issue #168) |
| src/lib/voice-policy.ts | Voice policy — consent state machine, audio size limit, log redaction, provider status (pure, issue #168) |
| src/lib/shell-state.ts | Capability shell-state computation: backend state × matrix row → not-selected|down|old|unsupported|full |
| src/lib/settings-shell-state.ts | Settings shell-state computation: backend state × matrix row → supported|unsupported|unreachable (pure, issue #121) |
| src/lib/session-source.ts | Sessions + stream contract (issue #120): per-user row, SSE chunk shape, id validator, capability-driven canStop / canShowRetry |
| src/lib/stream-buffer.ts | SSE chunk dedupe + reconnect helper (issue #120): StreamBuffer (hard-floor dedupe at highestSeq), bounded exponential backoff with jitter, terminal-flag-aware reconnect |
| src/lib/session-page-state.ts | Page state machine (issue #120): loading | down | ready | stream | closed, capability-driven gates, backend-switch invalidation |
| src/lib/sessions-fixture.ts | Per-user sessions fixture + cursor helper (issue #120): shape validator + selectUserSessions / findSessionForUser / nextChunk |
| src/app/api/v1/addons/hermes-desktop/sessions/route.ts | GET /sessions (issue #120): per-user slice + capability-flagged canStop / canRetry |
| src/app/api/v1/addons/hermes-desktop/sessions/[id]/stream/route.ts | GET /sessions/{id}/stream (issue #120): SSE responder, advances cursor based on Last-Event-ID |
| src/app/api/v1/addons/hermes-desktop/sessions/[id]/stop/route.ts | POST /sessions/{id}/stop (issue #120): capability-gated, idempotent on already-stopped |
| src/app/api/v1/addons/hermes-desktop/sessions/[id]/retry/route.ts | POST /sessions/{id}/retry (issue #120): capability-gated, idempotent on already-streaming |
| src/components/HermesSessionsPage.tsx | Sessions UI (issue #120): per-user list + stream pane + capability-gated Stop / Retry + backend-switch cleanup |
| src/page-sessions.ts | Page descriptor for the sessions UI (ADR-001 dual-registration) |
| src/lib/workspace-fs.ts | Per-user workspace file browser + sandboxed preview envelope (issue #167): FsAdapter, normalizeRelativePath, resolveSafePath, listDirectory, readPreview, sandboxFor, cspFor. Pure — every fs call goes through the caller-supplied adapter so the unit tests pass an in-memory Map |
| src/app/api/v1/addons/hermes-desktop/files/route.ts | GET /files (issue #167): per-user workspace listing, capability-gated, secret-free, no file:// URL |
| src/app/api/v1/addons/hermes-desktop/preview/route.ts | GET /preview (issue #167): per-user sandboxed preview envelope, capability-gated, secret-free, no file:// URL, active content sandboxed (no allow-same-origin) |
| src/components/HermesWorkspacePage.tsx | Workspace UI (issue #167): file tree + side-by-side preview pane, capability-gated, sandboxed iframe for active content |
| src/page-workspace.ts | Page descriptor for the workspace UI (ADR-001 dual-registration) |
| src/lib/auth-fixture.ts | Auth test fixtures (4 scenarios: authenticated-anon, missing-token, bad-signature, backend-switch) |
| src/lib/timeout-fixture.ts | Timeout test fixtures (DB / network > 30s → degraded) |
| src/lib/version-fixture.ts | Version test fixtures (down / old / pinned-commit match) |
| tests/unit/*.test.cjs | Legacy node --test suite covering the acceptance criteria |
| tests/unit/*.test.ts | Vitest suite covering the acceptance criteria (mirrors the .test.cjs files) |
| AC | Test |
|----|------|
| Matrix pro Upstreamfeature: Commitpfad, Aiopta-Vertrag, full|partial|missing|unsupported, Test/Gap | tests/unit/matrix.test.cjs validates every row's shape; tests/unit/manifest.test.cjs asserts the matrix rows match the manifest contract |
| Adapter liefert authenticated, secret-free status und invalidiert bei Backendwechsel | tests/unit/capability-adapter.test.cjs — happy path + 4 auth-fixture scenarios + backend-switch invalidation |
| Shell zeigt not-selected/down/old/unsupported; keine optimistischen Flags | tests/unit/shell-state.test.cjs — every state transition is asserted against the matrix + backend state tuple; no test ever passes when a down row renders as full |
| Manifest-/Adapter-/Auth-/Timeout-/Versionfixtures und validate:addons grün | scripts/validate-addons.sh (exits 0) + the four fixture files plus their dedicated unit tests |
| Issue #120: Nur eigene Sessions sichtbar | tests/unit/sessions-route.test.cjs (Alice sees her sessions, Bob sees his, cross-user probe returns same shape as missing) + tests/unit/sessions-fixture.test.cjs (selectUserSessions + findSessionForUser) |
| Issue #120: Stop/Retry folgt Capability-Flags | tests/unit/sessions-route.test.cjs (capability flags threaded per row) + tests/unit/stop-route.test.cjs + tests/unit/retry-route.test.cjs (501 on unsupported/missing, 200 on full/partial, 409 on invalid state) + tests/unit/session-page-state.test.cjs (canStop/canRetry gated by verdict) |
| Issue #120: Streaming dupliziert keine Chunks | tests/unit/stream-buffer.test.cjs (hard-floor dedupe at highestSeq + recent-set dedupe + bounded eviction) + tests/unit/stream-route.test.cjs (Last-Event-ID cursor + SSE id: line) |
| Issue #120: Addon deaktivieren entfernt Navigation und beendet Polling/Streams | src/components/HermesSessionsPage.tsx useEffect cleanup closes the EventSource + clears the reconnect timer on unmount |
| Issue #120: Hermes down → retrybarer degraded state | tests/unit/session-page-state.test.cjs (down state + RETRY transition) + tests/unit/sessions-route.test.cjs (BACKEND_DOWN → 503 typed error) |
| Issue #120: Streamabbruch → reconnect oder klar beendet | tests/unit/stream-buffer.test.cjs (shouldReconnect honours terminal flag + attempt cap; selectReconnectBackoff is bounded at 8s with half-jitter) + HermesSessionsPage reconnects with ?resume=<nextSeq> |
| Issue #120: Backendwechsel beendet Subscriptions und leert stale Sessions | tests/unit/session-page-state.test.cjs (BACKEND_SWITCH transitions from ready/stream/down to closed) + HermesSessionsPage backend-switch watcher |
| Issue #167: Capability-gated Files/Previews mit per-User Workspace-root | tests/unit/workspace-fs.test.cjs (per-user root, workspace-root cap, scopedStore-ready) + tests/unit/files-route.test.cjs (per-user resolveWorkspaceRootForUser + 401 on missing/bad signature) + tests/unit/preview-route.test.cjs (per-user envelope) |
| Issue #167: Path traversal, symlink escape, oversized/binary/unsupported sauber behandelt | tests/unit/workspace-fs.test.cjs (TRAVERSAL via .., \\\\, NUL, symlink escape via resolveSafePath realpath check, OVERSIZED via maxBytes + 1 round-trip, BINARY via extension + NUL-byte sniff, UNSUPPORTED via non-whitelisted mime) + tests/unit/files-route.test.cjs (every code → status mapping) |
| Issue #167: Preview ist sandboxed; aktiver Inhalt erhält keine Core-Origin-Rechte | tests/unit/workspace-fs.test.cjs (sandboxFor returns allow-popups for text/html + application/pdf, NEVER allow-same-origin; cspFor returns default-src 'none', NEVER script-src) + tests/unit/preview-route.test.cjs (envelope carries sandbox + csp for every mime, response is secret-free) |
| Issue #167: Adapter verwendet ausschließlich Aiopta Workspace-/Artefakt-APIs; keine freien Hostpfade oder file://-URLs | tests/unit/workspace-fs.test.cjs (response shape is secret-free, listing entries are RELATIVE paths, envelope never carries file://) + tests/unit/preview-route.test.cjs (response body never contains file:// or the absolute path) |
| Issue #167: FS/AuthZ/preview sandbox Matrix und zwei User | tests/unit/two-user-isolation.test.cjs (user-a + user-b see different content, path-traversal blocked, symlink to other user blocked as SYMLINK_ESCAPE, error body never carries another user's file content) |
| Issue #121: Jedes Matrixfeature hat UI-Zustand supported/unsupported/unreachable | tests/unit/settings-shell-state.test.cjs — full truth table + "no optimistic flags" guard |
| Issue #121: Modelloptionen stammen aus Aiopta-Konfiguration | tests/unit/settings-adapter.test.cjs — source reference binds to Aiopta routes (SETTINGS_SOURCE_BINDINGS) |
| Issue #121: Memory/Automation zeigen Aktualität und Fehlerzustand | tests/unit/settings-adapter.test.cjs — lastRefreshedAt + errorCode surfaces, plus tests/unit/settings-route.test.cjs |
| Issue #121: Keine internen Hosts/Secrets im Browserpayload | tests/unit/settings-adapter.test.cjs — JSON-stringified verdict scan forbids token, password, secret, apikey, bearer, credential, http://, https://, localhost, 127.0.0.1, 0.0.0.0 |
| Issue #121: Capability-Matrix-Tests | tests/unit/matrix.test.cjs §"issue #121 — settings-group rows" pins every settings-group row |
| Issue #121: Komponententests für supported/unsupported/down | tests/unit/settings-shell-state.test.cjs (every state × every backend) |
| Issue #121: E2E Backendwechsel Hermes → anderer Provider | tests/unit/settings-backend-switch.test.cjs — hermes → openclaw with mixed live-state per row |
- Upstream self-update is unsupported (by design). The addon never
advertises "update available" — there is no Hermes-desktop self-update
surface. Updates flow through the normal Aiopta Marketplace ZIP-artifact
release pipeline.
- Hermes desktop app itself is not in this repo. The matrix binds
upstream features to Aiopta contracts; it does not re-implement the
Hermes client.
- DB schema — this addon ships no migrations/ directory. All state
lives in the matrix JSON + the request-scoped adapter cache + the
per-user sessions fixture (issue #120). No scopedStore, no per-user
table, no FK.
- Browser → Hermes direct (issue #120 neg-scope). The browser never
talks to Hermes directly; every session / stream / stop / retry call
flows through the Aiopta userRoute-wrapped handler in this addon.
- Cross-user session access (issue #120 neg-scope). The sessions
list is filtered by auth.id. A cross-user probe returns the same
answer as a missing id — no enumeration leak.
- Setting values (issue #121 neg-scope). The settings verdict
surfaces the Aiopta route that owns the value + recency + error code.
It never returns the value of a setting (model id, API key,
personality content, memory content, automation payload). The user
clicks "Manage in Aiopta" to reach the surface that owns the value.
npm run validate:addons # addon schema + matrix pin guard\nnode --test addons/hermes-desktop/tests/unit/*.test.cjsThe Jenkins PR-check pipeline runs both as part of ci:build.
All notable changes to the hermes-desktop addon are documented here.
This addon follows Semantic Versioning.
- Per-user workspace file browser — `GET
/api/v1/addons/hermes-desktop/files?path=<relative>` returns a
listing of the calling user's workspace root only. The endpoint
is per-user (scopedStore(userId).workspaces), capability-gated
(addons/hermes-desktop/files), and secret-free (the response
never carries a token, bearer, or credential; the listing
entries are RELATIVE paths only).
- Per-user sandboxed preview — `GET
/api/v1/addons/hermes-desktop/preview?path=<relative>` returns
a PreviewEnvelope (mime, content, encoding, size,
sandbox, csp, truncated). HTML / PDF previews carry
sandbox="allow-popups" (NEVER allow-same-origin, NEVER
allow-scripts) and a CSP that defaults to default-src 'none'
— active content cannot reach the core origin. PDF bodies are
base64-encoded; text / markdown / JSON / HTML bodies are
UTF-8. The shell renders the envelope via `<iframe sandbox
srcdoc=...> or <pre> for text. There is no file://` URL
and no path the shell could follow.
- Path-traversal / symlink-escape / binary / oversize guards
— implemented in src/lib/workspace-fs.ts. Every filesystem
call goes through a caller-supplied FsAdapter so the unit
tests pass an in-memory Map-backed mock; the route handler
passes node:fs/promises. The route handler maps the
WorkspaceFsError.code to a stable HTTP status: 400 (TRAVERSAL
/ ABSOLUTE_PATH / NOT_A_DIRECTORY), 404 (NOT_FOUND /
SYMLINK_ESCAPE), 413 (OVERSIZED), 415 (BINARY / UNSUPPORTED).
- Matrix rows — feat-side-by-side-previews and
feat-file-browser move from missing to partial (issue
#167 closes the upstream follow-up; the Aiopta side is
capability-gated and secret-free). Two new contract rows are
added: feat-preview-sandbox (full) and feat-no-file-url
(full).
- Workspace page + capability flags — HermesWorkspacePage
composes the file tree + a side-by-side preview pane. New
capabilities: hermes-workspace-files, hermes-workspace-preview,
preview-sandboxed, no-file-url. New skill:
hermes-desktop-workspace (permissions for both routes; the
agent must have both before calling /preview).
- tests/unit/workspace-fs.test.cjs — 69 tests covering the pure
module: path normalisation, symlink escape, binary detection,
mime classification, sandbox/CSP contract, secret-free response
shape.
- tests/unit/files-route.test.cjs — 24 tests covering the route
handler: auth gate, happy path, capability gating, error code
→ status mapping.
- tests/unit/preview-route.test.cjs — 22 tests covering the
preview route: envelope shape, sandbox contract, no-file-url
contract, per-user workspace, security guards.
- tests/unit/two-user-isolation.test.cjs — 8 tests covering
the Pflicht-Test "Cross-User-Zugriff: 404 statt 403" for both
routes (file browser + preview).
- Per-user Hermes sessions UI — a new page at
/addons/hermes-desktop/sessions that lists the calling user's
Hermes sessions, opens an SSE stream, and offers Stop / Retry
only when the capability adapter reports feat-chat-streaming
as full or partial.
- Per-user sessions API — `GET
/api/v1/addons/hermes-desktop/sessions` returns the user's slice
only. Cross-user probes are merged with missing-id responses so a
caller cannot enumerate session ids by HTTP status (issue #120
AC #1: "Nur eigene Sessions sichtbar").
- Capability-gated SSE stream — `GET
/api/v1/addons/hermes-desktop/sessions/{id}/stream` emits one
chunk per request. The browser dedupes by sequence id; the route
advances the cursor based on Last-Event-ID so a reconnect
resumes from the next chunk (issue #120 AC #3: "Streaming
dupliziert keine Chunks"). The browser's StreamBuffer adds a
hard floor at highestSeq so a buggy backend cannot trick the UI
into rendering an old chunk.
- Capability-gated Stop / Retry — `POST
/api/v1/addons/hermes-desktop/sessions/{id}/stop and POST
/api/v1/addons/hermes-desktop/sessions/{id}/retry` are gated by
the capability verdict for feat-chat-streaming (issue #120
AC #2: "Stop/Retry folgt Capability-Flags"). unsupported /
missing row → 501. Already-stopped → 200 (idempotent). Invalid
state → 409.
- Pinned upstream + image-compatibility contract (issue #169):
hermes-desktop.pin.json now stores, displays and validates
together with the source commit:
- image — OCI registry/repository reference
- imageDigest — sha256-pinned image digest
(^sha256:[a-f0-9]{64}$, no latest)
- apiSchemaVersion — pinned Semver of the upstream API contract
- license — upstream license string (now mandatory +
hard-validated against the canonical value)
- compatibilityIssue — reference to issue #169 (this entry)
- hermes-desktop-parity.json mirrors every contract field in its
pin block; the matrix JSON Schema (hermes-desktop-parity.schema.json)
requires the new fields.
- src/lib/pin.ts — pure pin loader/validator + compareSemver +
classifyApiSchemaCompatibility for the new API-schema drift
verdict (compatible | older | newer | unknown).
- Adapter verdict (src/lib/capability-adapter.ts) carries the
full pinned contract: pinImage, pinImageDigest,
pinApiSchemaVersion, pinLicense, compatibilityIssue,
apiSchemaCompatible, backendApiSchemaVersion. Each
VerdictRow carries the per-evaluation imageDigestOk and
apiSchemaVersionOk columns so the shell can render a precise
reason without re-running the adapter.
- New shell state 'unsupported-version' (issue #169 AC #2): API
schema drift on a full row surfaces unsupported-version,
distinct from down (image-digest mismatch / backend unreach-
able) and old (commit drift).
- BackendState carries new mandatory fields imageDigestOk and
apiSchemaVersionOk (defaults to false — no optimistic
default).
- src/app/api/v1/addons/hermes-desktop/capabilities/route.ts
reads the backend's reported API schema version from a
deterministic file (.backend-api-schema.json) and surfaces the
full pinned contract under data.pinContract in the response.
- Validator (scripts/validate-addons.cjs):
validateHermesDesktopPin hard-validates every contract field
(image + imageDigest + apiSchemaVersion + license +
compatibilityIssue). validateHermesMatrix hard-fails on any
drift between the matrix pin block and the pin JSON.
- New unit test tests/unit/pin.test.cjs (issue #169 contract):
every required field is present + drift surfaces a typed
PinLoadError with a precise field pointer.
- Existing tests extended:
tests/unit/capability-adapter.test.cjs covers the new
imageDigestOk / apiSchemaVersionOk semantics + the
apiSchemaCompatible verdict.
scripts/validate-addons.test.cjs covers every drift scenario
for the new pin fields.
- Backend-switch cleanup — when the verdict's backend id
changes between refreshes the page tears down every open
EventSource + clears the session list (issue #120 edge-case:
"Backendwechsel beendet Subscriptions und leert stale
Sessions").
- Page state machine — src/lib/session-page-state.ts
implements a typed reducer over `loading | down | ready | stream
| closed with transitions for LOADED, LOAD_FAILED`,
SELECT_SESSION, CHUNK_RENDERED, STREAM_TERMINAL, STOP,
RETRY, BACKEND_SWITCH, AUTH_LOST. Pure, fully unit-tested.
- Sessions fixture — a git-ignored
addons/hermes-desktop/.sessions-fixture.json (local test seam)
holds the per-user session slices + stream chunks the route
handlers consult. The shape is validated by loadSessionsFixture
so a malformed fixture fails the route handler with 503, never
silently downgrades to an empty list.
- New skill — hermes-desktop-sessions exposes the per-user
sessions endpoint to Aiopta's agent layer. Secret-free by
construction (issue #101 invariant preserved).
- Settings panel (model / personality / skills / memory /
automation-status) backed by a new endpoint and a new shell-state
vocabulary (issue #121). The matrix is extended with an optional
group field (currently the only allowed value is "settings");
the five settings-group rows are tagged accordingly.
- src/lib/settings-shell-state.ts — pure shell-state computation
that maps a backend state × matrix row to a discrete state
(supported | unsupported | unreachable). The verdict is never
optimistic: a missing matrix row stays unsupported regardless of
live-source health, and a full/partial/different row on an
unreachable / erroring / never-observed source renders as
unreachable.
- src/lib/settings-adapter.ts — pure, secret-free adapter. Reads the
matrix once at construction, filters rows whose `group ===
"settings"`, and returns a per-row settings verdict keyed by
(backend, live-state-hash). The verdict is whitelist-serialized
by serializeSettingsSecretFree so a future contributor adding a
new field cannot leak a credential, an internal host, a base URL,
or a setting value. Stable error code namespace:
SOURCE_UNREACHABLE, SOURCE_ERRORED, SOURCE_NEVER_OBSERVED.
- src/components/SettingsPanel.tsx — shell page that renders the
per-row settings verdict with the discrete shell state + last-
refreshed timestamp + stable error code + Aiopta route reference.
- src/app/api/v1/addons/hermes-desktop/settings/route.ts —
authenticated, secret-free settings endpoint. Reads the live per-row
state from addons/hermes-desktop/.settings-state.json and falls
back to emptySettingsBackendState() when the file is missing.
Hard 30s timeout on the adapter evaluation.
- Updated src/manifest.ts to register the new settings route + the
new skill (alongside the existing sessions routes from issue #120)
and the bumped version (0.2.0).
- Updated addon.json to register the new endpoint + skill +
capabilities (settings-panel, settings-shell-state) in addition
to the existing sessions endpoints/capabilities (issue #120).
- Updated hermes-desktop-parity.schema.json to accept the optional
group field.
- New unit tests (issue #121):
settings-shell-state.test.cjs (full truth table + no-optimistic-
flags guard), settings-adapter.test.cjs (happy path + secret-free
invariant + cache invalidation on backend switch + cache
invalidation on live-state change + cache TTL + error code mapping),
settings-route.test.cjs (auth gate + happy path + secret-free
response + per-row state mapping), settings-backend-switch.test.cjs
(E2E backend-switch test, hermes → openclaw).
- hermes-desktop.pin.json schema extended additively — every
existing field is preserved; the four new fields are mandatory.
- hermes-desktop-parity.json pin block extended additively with
the four contract fields + compatibilityIssue.
- src/lib/shell-state.ts truth-table now distinguishes image-
digest mismatch (down) from API-schema drift on full rows
(unsupported-version).
- src/lib/matrix.ts validateMatrix accepts the optional
expectedPin argument and hard-fails on drift between matrix
and pin JSON for every contract field.
- The 16-row matrix keeps all rows; the image-pin row status is
unchanged (still missing) because the surface-level pin UI is
out of scope for this issue. The data model + validator hardening
IS the contract surface this issue ships.
- addon.json — version 0.2.0; capabilities extended with
image-digest-pinned, api-schema-version-pinned,
supply-chain-checked (issue #169) and
hermes-sessions, hermes-streaming, hermes-stream-stop,
hermes-stream-retry (issue #120); endpoint list extended with
the four new routes; pages[] now also carries
hermes-desktop-sessions-page.
- src/manifest.ts — registers the four new routes + the new
page descriptor; pages: [hermesDesktopPage, hermesSessionsPage].
- hermes-desktop-parity.json — feat-chat-streaming and
feat-sessions rows now have followUpIssue: null (the UI
surface shipped in #120). Status remains partial because the
page is wired against a local fixture rather than a live chat
backend driver — that live integration is a future follow-up.
- feat-tool-activity row still references #120 as the
follow-up (the timeline is still routed through chat UI; this
slice did not address it).
- New lib modules: src/lib/session-source.ts (typed contract),
src/lib/stream-buffer.ts (dedupe + reconnect helper),
src/lib/session-page-state.ts (page state reducer),
src/lib/sessions-fixture.ts (fixture validator + helpers).
- New routes: src/app/api/v1/addons/hermes-desktop/sessions/route.ts
+ sessions/[id]/{stream,stop,retry}/route.ts.
- New tests: tests/unit/{stream-buffer,session-page-state,sessions-fixture,sessions-route,stream-route,stop-route,retry-route}.test.cjs
+ tests/unit/_sessions-fixture-shared.cjs (pure helper module
shared by the route tests).
- tests/unit/manifest.test.cjs extended to assert the new
capabilities, endpoints, skills, and pages[] entries.
- Path-param fix for sessions/[id]/{stream,stop,retry} route
handlers: read id from context.params.id (awaited per Next.js
15) instead of req.nextUrl.searchParams (the old code returned
400 for every stream/stop/retry call).
- ✅ Jedes Matrixfeature hat UI-Zustand supported/unsupported/unreachable —
settings-shell-state.test.cjs pins every state × backend combination.
- ✅ Modelloptionen stammen aus Aiopta-Konfiguration — SETTINGS_SOURCE_BINDINGS
binds each matrix row to its Aiopta route; the verdict surfaces the
reference, never the value.
- ✅ Memory/Automation zeigen Aktualität und Fehlerzustand — lastRefreshedAt
+ errorCode are first-class verdict fields.
- ✅ Keine internen Hosts/Secrets im Browserpayload — serializeSettingsSecretFree
whitelist + JSON-stringified scan forbids token/password/secret/
apikey/bearer/credential/http:///https:///localhost/127.0.0.1/0.0.0.0.
- ✅ Capability-Matrix-Tests — matrix.test.cjs §"issue #121 — settings-group
rows" pins every settings-group row.
- ✅ Komponententests für supported/unsupported/down — settings-shell-state.test.cjs.
- ✅ E2E Backendwechsel Hermes → anderer Provider — settings-backend-switch.test.cjs.
- hermes-desktop.pin.json — commit-pinned reference to
NousResearch hermes-agent @ea8a8b4af8612b655a5bbfc74eba21e1e806758d.
- hermes-desktop-parity.json — 16-row feature matrix binding every
upstream Hermes desktop capability to an Aiopta contract (route +
skill + UI + test) with a status of
full|partial|missing|unsupported|different.
- hermes-desktop-parity.schema.json — JSON Schema (draft-07) for the
matrix shape; the validator enforces the same shape at PR-check time.
- Capability adapter (src/lib/capability-adapter.ts) — pure, backend-
aware, cache-aware, secret-free. Cache invalidates on backend switch.
- Shell state computation (src/lib/shell-state.ts) — maps a backend
state × matrix row to a discrete shell state
(not-selected|down|old|unsupported|full). No optimistic flags.
- Adapter endpoint (src/app/api/v1/addons/hermes-desktop/capabilities)
— authenticated, secret-free. Returns status + references, never
credentials.
- Shell page (src/components/HermesDesktopPage.tsx) — renders the
matrix + the live verdict. Every cell carries the upstream commit
ref + the follow-up issue (when status ≠ full).
- Auth / timeout / version fixtures (src/lib/auth-fixture.ts,
timeout-fixture.ts, version-fixture.ts) — 4 + 3 + 3 scenarios
each, driven by unit tests so a future change cannot silently weaken
the contract.
- Validator hooks in scripts/validate-addons.cjs:
validateHermesDesktopPin (commit pin equals canonical SHA) and
validateHermesMatrix (16 unique rows, all upstream
commits equal the pin, every missing|different row carries a
numeric followUpIssue).
- Unit tests:
matrix.test.cjs, capability-adapter.test.cjs,
shell-state.test.cjs, auth-fixture.test.cjs,
timeout-fixture.test.cjs, version-fixture.test.cjs,
capabilities-route.test.cjs, manifest.test.cjs.
Monitor and control Home Assistant entities — lights, climate, sensors, switches, locks,
automations, scenes and scripts — via the HA REST API. Edit automation/scene/script **code as
YAML, manage Lovelace dashboards (Views + Cards), Helpers (input_*) and Areas**, and expose a
Aiopta agent as a Home Assistant voice assistant. Onboard the upstreamhomeassistant-ai/ha-mcp MCP server so Aiopta agents can read HA over MCP.
- Addon-ID: homeassistant
- Version: 1.0.0
- Fähigkeiten: entity-browser, entity-control, dashboard, automation-trigger,
yaml-config-editor (automation/scene/script), lovelace-dashboards, helpers-management,
areas-management, voice-assistant (Aiopta agent as HA conversation agent), connection-config,
mcp-onboarding (ha-mcp setup flow, addons#179)
1. HA-Verbindung (Settings-Zahnrad oben rechts): Home-Assistant-URL +
Long-Lived Access Token. Wird unter data/homeassistant-config.json gespeichert; **kein
hartkodierter Host**, kein Secret im Repo.
2. Voice Assistant (optional, Tab „Voice"): Aiopta-Agent auswählen, der HA-Assist beantwortet.
3. HA-MCP für Agenten (Abschnitt oben auf der HA-Seite, ab addons#179): das Upstream-Add-on
homeassistant-ai/ha-mcp einbinden, damit MCP-fähige Agenten Home Assistant lesen können. Wird
unter dem Per-User-Slug home-assistant in der MCP-Addon-Datenbank gespeichert (kein zweites
Secret in homeassistant-config.json). Feature-gated auf das mcp-Addon (ADR-047) — ist das
MCP-Addon nicht installiert oder deaktiviert, erscheint eine klare Installieren-/Aktivieren-
Handlung; die klassische REST/WS-Verbindung bleibt unabhängig nutzbar.
Für Automationen, Szenen und Skripte lässt sich der tatsächliche Code (YAML) bearbeiten — nicht
nur der Name.
- Tab Automations → Button „Edit YAML" (oder Tabs Scenes / Scripts → „YAML").
- Der Editor lädt das HA-Config-Objekt als YAML (GET …/<domain>s/[id]/yaml), prüft die Eingabe
live mit js-yaml (gültig/ungültig-Status) und speichert über PUT …/<domain>s/[id]/update
mit { yaml }.
- Server-seitig wird das YAML vor dem Schreiben geparst + validiert (validateYaml in
src/lib/yaml.ts); nur ein gültiges Config-Objekt geht an HA
(POST /api/config/<domain>/config/<object_id>) — nie roher YAML-Text, nie ein leeres/null/
Listen-/Skalar-Dokument (das würde den Eintrag zerstören).
- Domains sind auf automation / scene / script whitelisted; alle drei sind voll editierbar.
Die HA-Config-API (/api/config/automation/config/<id>) ist nicht über den Entity-Slug
(automation.wohnzimmer_indirekt_ein) ansprechbar, sondern nur über die echte attributes.id
(numerische/uuid unique_id) — und sie bedient nur .storage/UI-definierte Automationen.
- id-Auflösung: Beim Lesen/Schreiben einer Automation wird zuerst die echte attributes.id aus
dem Entity-State (GET /api/states/automation.<slug> → attributes.id) aufgelöst und diese an
die Config-API gegeben (src/lib/client.ts → resolveAutomationConfigId). Das war die Ursache des
404 / der leeren Trigger/Action im „Edit Routine"-Dialog.
- YAML-Automationen (kein Config-Eintrag): Schlägt die Config-API mit 404 fehl (Automation
liegt in automations.yaml), wird best-effort die WebSocket-API versucht; bietet HA die
Config dort nicht an, kommt eine klare, typisierte Meldung zurück (HaYamlOnlyError, HTTP
422, { readOnly:true, reason:"yaml_defined" }) — „YAML-definiert, hier nur lesbar; in HA
bearbeiten". Nie ein nacktes 404 in der UI; der Edit-Dialog zeigt entweder echte Trigger/Action
oder einen klaren Grund.
- Lesen/Schreiben/Löschen einer Routine laufen über src/lib/automations.ts
(readAutomationConfig / writeAutomationConfig / deleteAutomationConfig); Enable/Disable/Trigger
über automation.turn_on|turn_off|trigger.
Das Addon (und ein Aiopta-Agent als HA-Voice-/Routinen-Schreiber) deckt über die Aiopta-API **lesend und
schreibend** ab:
- Entitäten/Sensoren: lesen (GET /entities, /entities/[id]), schalten/setzen
(POST /entities/[id]/toggle, /entities/[id]/service → /api/services/<domain>/<service>).
- Automationen/Routinen: lesen + anlegen + ändern + aktivieren/deaktivieren + auslösen + löschen
(id-Auflösung + WS-Fallback wie oben).
- Szenen / Skripte: lesen/anlegen/löschen/reload + YAML-Edit.
- Helpers (input_*) / Areas: lesen/anlegen/ändern/löschen (WS).
- Lovelace-Dashboards: Views/Karten lesen + speichern (No-Wipe-Garantie).
Aufbauend auf der YAML/Entity/Config-Basis (ADR-018) lassen sich weitere HA-Konfigurationsflächen
direkt aus Aiopta verwalten. Aiopta-API only; HA über den Addon-Client (URL+Token aus der
Addon-Config, Token wird nie geloggt).
WS-only-Flächen laufen über einen kleinen global-WebSocket-Helper (src/lib/ha-ws.ts) —
keine neue Dependency (Node-22-Built-in): eine authentifizierte WS wird geöffnet
(auth_required→auth→auth_ok), ein Kommando gesendet, das Ergebnis abgewartet, dann
geschlossen. Wo HA REST anbietet (Szenen/Skripte-Config) wird REST bevorzugt.
- Tab Dashboards — Lovelace-Dashboards auflisten/anlegen/löschen und die Views + Karten eines
Dashboards als YAML bearbeiten (lovelace/config get, lovelace/config/save set,
lovelace/dashboards/list|create|delete). Vor dem Speichern wird die Form geprüft (Objekt mit
views[]) — eine ungültige/leere Konfiguration wird abgelehnt, damit ein Dashboard nie
überschrieben/geleert wird (validateLovelaceConfig in src/lib/yaml.ts, client und server).
- Tab Helpers — input_boolean, input_number, input_text, input_select, input_datetime,
input_button: auflisten/anlegen/ändern/löschen über die WS-Collections
(<domain>/list|create|update|delete); nur diese Domains sind erlaubt.
- Tab Areas — Bereiche auflisten/anlegen/umbenennen/löschen über die Area-Registry
(config/area_registry/list|create|update|delete).
- Szenen & Skripte — der YAML-Editor (oben) deckt die Config ab; zusätzlich gibt es
list/create/delete/reload über die HA-Config-API (/api/config/<domain>/config/...,
<domain>.reload).
Geparkt (Owner/Folge-Arbeit, docs/OPEN-DECISIONS.md): Entitäten/Geräte einem Bereich
zuweisen (ha-area-entity-assignment), HA-Version-abhängige WS-Edge-Cases
(ha-ws-auth-edge-cases).
ha-lovelace-visual-designer ist nicht mehr geparkt — die Kartenbibliothek im
Dashboard-Reiter ist mit addons#932 gebaut.
Ein zweiter, vom klassischen REST-Pfad unabhängiger Onboarding-Weg bindet das Upstream-Add-onhomeassistant-ai/ha-mcp ein, damit MCP-fähige Agenten die HA-Instanz über MCP lesen können.
Standardmäßig read-only — destruktive Tools (ha_config_set_yaml, ha_write_file,ha_delete_file, ha_rename_entity, rohe YAML / Filesystem / Delete) bleiben blockiert und
brauchen eine separate explizite Freigabe (siehe #178, mcp-tool-policy.ts).
- UI: Abschnitt „Home Assistant MCP for agents" oben auf der HA-Seite (HaMcpSetupSection.tsx).
URL + optionales Bearer-Token + Default-read-only-Toggle, plus eine sichtbare State-Machine
(not configured → saved/disabled → connecting → tools discovered → ready | konkreter Fehler).
Der Bereich erscheint auch wenn die klassische REST-Verbindung nicht konfiguriert ist, damit
reine ha-mcp-Nutzer ohne REST-Token onboarden können.
- Chat: Agent-Skill homeassistant-ha-mcp-setup (siehe addon.json). Deterministischer Dialog
(URL → Token → read-only → Setup → Resultat), identische Validierung und Idempotenz wie die UI.
- Feature-Gating: der gesamte Bereich ist in <FeatureGate addonId="mcp"> eingebettet (ADR-047).
Ohne / mit deaktiviertem MCP-Addon erscheint der Standard-„needs the MCP addon — enable it"-
Panel mit Link auf den Addon-Manager; die REST-Verbindung bleibt nutzbar.
- Server-Storage: Per-User-Slug home-assistant in der mcp_servers-Tabelle des MCP-Addons
(addons/mcp/src/lib/mcp-server-store.ts). Kein zweites HA-MCP-Secret in
homeassistant-config.json — die direkte HA-Config bleibt unverändert.
- Secret-Handling: die zufällige Secret-Path-Komponente der ha-mcp-URL ist ein Credential. Sie
wird per User gespeichert, aber maskMcpServer maskiert sie auf jeder GET-Antwort, sobald das
Feld metadata.credentialInUrl: true gesetzt ist (Antwort zeigt nur Origin +
••••••). Der Bearer-Token folgt dem bestehenden auth.token → "••••••"-Vertrag. Beide werden
in UI / Chat / Logs / Fehlern nie im Klartext ausgegeben — sanitiseHaMcpError entfernt Bearer-
Header und /private_<token>-Pfade aus jeder Fehlermeldung, bevor sie die Komponente oder den
Chat erreicht.
- Idempotenz: Mehrfaches Speichern mit unveränderter URL/Token ist ein No-op auf dem Wire; ein
PATCH mit leerem Token löscht kein bestehendes Token; eine vorhandene strengere Policy
(z. B. manuelle deniedTools-Liste unter read-only) wird nicht gelockert; eine vorhandene
weitere Policy (write/full) wird auf read-only zurückgesetzt.
- Identity-Check: nach discover und sync-tools prüft der Flow, dass mindestens einer der
ha-mcp-Identitätsmarker (ha_get_overview ODER ha_get_skill_guide) im entdeckten Toolset
vorhanden ist. Ein beliebiger fremder MCP-Server wird nicht still als Home Assistant
aktiviert; bei fehlendem Marker bleibt der Server deaktiviert und der Retry ist möglich.
- Kein Fake-Green: der Server wird nur aktiviert, wenn Handshake + Identity-Check grün sind.
Bei jedem Fehlschlag bleibt der Datensatz deaktiviert und retry-fähig.
- OAuth: im ersten Schritt nicht unterstützt — statischer Bearer-Token (bzw. der vom Upstream
auf HA OS / Supervised vererbte Supervisor-Token) ist der einzige aktuelle Auth-Flow, bis #177
explizit einen OAuth-Flow nachliefert.
- Video + Upstream: siehe Video https://youtu.be/AL391nkWGIc und Upstream-Repository
https://github.com/homeassistant-ai/ha-mcp. Kein Forken / Vendoren / eigenes Container-
Image; Aiopta greift ausschließlich über die HA-Add-on-Logs auf die vom Nutzer bereitgestellte
URL zu.
Installationsschritte HA-Seitig (Owner-Aktion, automatisierbar in einer Folge-Story):
\n1. Repository https://github.com/homeassistant-ai/ha-mcp im HA Add-on Store hinzufügen.
2. Home Assistant MCP Server installieren und starten.
3. Vollständige Endpoint-URL (inkl. Secret-Path) aus dem Add-on-Log kopieren.
4. In Aiopta im HA-Add-on-Bereich „Home Assistant MCP for agents" einfügen und Setup starten.
5. Auf HA OS / Supervised ist kein zusätzlicher Long-Lived Token nötig — das Upstream-Add-on
erkennt die Supervisor-Verbindung selbst.
Ein Mission-Control-Agent kann HA-Assist beantworten. Aiopta stellt den Endpunkt; HA zeigt
seinen Conversation-Agent darauf.
- Tab Voice: Aiopta-Agent auswählen (aus /api/v1/agents/my-agents), Endpunkt-URL kopieren,
Setup-Schritte ansehen. Auswahl wird als HA_ASSIST_AGENT_ID in der Addon-Config gespeichert.
- Endpunkt: POST /api/v1/addons/homeassistant/assist mit
{ text, conversation_id?, agentId? }. Der Text wird über @/lib/gateway an den gewählten Agenten
geroutet (dessen Soul + Modell-Kette + Fallbacks, Backend-Binding) — kein direkter Provider-Call.
- Antwort: HA-conversation.process-Form
{ response: { speech: { plain: { speech } }, … }, conversation_id }. Fehler werden als
HA-Error-Response zurückgegeben (Assist bleibt am Leben), nicht als HTTP-Fehler.
- HA-Seite = Owner-Konfiguration (parked, ha-assist-agent-setup in
docs/OPEN-DECISIONS.md): in HA einen REST/Conversation-Agent auf den Endpunkt zeigen, mit einem
Aiopta-Agent-API-Key als Bearer-Token authentifizieren, und in eine Assist-Pipeline einhängen.
Bis dahin funktioniert die Aiopta-Seite vollständig; HA muss den Endpunkt nur erreichen.
| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/homeassistant/automations |
| GET | /api/v1/addons/homeassistant/automations/[id] |
| POST | /api/v1/addons/homeassistant/automations/[id]/toggle |
| POST | /api/v1/addons/homeassistant/automations/[id]/trigger |
| PUT | /api/v1/addons/homeassistant/automations/[id]/update |
| GET | /api/v1/addons/homeassistant/automations/[id]/yaml |
| GET | /api/v1/addons/homeassistant/scenes/[id]/yaml |
| PUT | /api/v1/addons/homeassistant/scenes/[id]/update |
| GET | /api/v1/addons/homeassistant/scripts/[id]/yaml |
| PUT | /api/v1/addons/homeassistant/scripts/[id]/update |
| POST | /api/v1/addons/homeassistant/assist |
| GET, PUT | /api/v1/addons/homeassistant/assist-config |
| GET, PUT | /api/v1/addons/homeassistant/config |
| GET | /api/v1/addons/homeassistant/entities |
| GET | /api/v1/addons/homeassistant/entities/[id] |
| POST | /api/v1/addons/homeassistant/entities/[id]/service |
| POST | /api/v1/addons/homeassistant/entities/[id]/toggle |
| GET, POST | /api/v1/addons/homeassistant/routines |
| GET, PUT, DELETE | /api/v1/addons/homeassistant/routines/[id] |
| GET, POST | /api/v1/addons/homeassistant/lovelace/dashboards |
| DELETE | /api/v1/addons/homeassistant/lovelace/dashboards/[id] |
| GET, PUT | /api/v1/addons/homeassistant/lovelace/dashboards/[id]/config |
| GET, POST | /api/v1/addons/homeassistant/helpers/[domain] |
| PUT, DELETE | /api/v1/addons/homeassistant/helpers/[domain]/[id] |
| GET, POST | /api/v1/addons/homeassistant/areas |
| PUT, DELETE | /api/v1/addons/homeassistant/areas/[id] |
| GET, POST | /api/v1/addons/homeassistant/scenes |
| DELETE | /api/v1/addons/homeassistant/scenes/[id] |
| POST | /api/v1/addons/homeassistant/scenes/reload |
| GET, POST | /api/v1/addons/homeassistant/scripts |
| DELETE | /api/v1/addons/homeassistant/scripts/[id] |
| POST | /api/v1/addons/homeassistant/scripts/reload |
| GET | /api/v1/addons/homeassistant/status |
| POST | /api/v1/addons/homeassistant/test |
- Alle Verwaltungsfunktionen (YAML-Editor, Dashboards, Helpers, Areas) verlangen eine konfigurierte
HA-Verbindung (URL + Token); ist HA nicht erreichbar, antworten die Routen mit einem klaren
Nicht-200-Status statt eines Absturzes.
- Dashboards: Kartenbibliothek (sechs Lovelace-Kartentypen: Kachel, Verlauf, Thermostat,
Energie, Kamera, Sensor-Gruppe) und YAML-Editor für Views/Karten. Beide arbeiten auf
derselben Konfiguration und speichern über denselben Weg — es gibt genau einen Speicherpfad
(saveDashboardConfig), damit kein Builder ein Dashboard leeren kann.
- Areas: Bereiche-CRUD; Entitäten/Geräte einem Bereich zuweisen ist geparkt
(ha-area-entity-assignment).
- Die HA-seitige Voice-Assistant-Verkabelung ist Owner-Konfiguration (siehe oben /
docs/OPEN-DECISIONS.md → ha-assist-agent-setup).
- HA-MCP-Onboarding (addons#179): Standard-Policy ist read-only. Der explizite
„Switch zu write / full"-Flow ist eine separate Folge-Story (nicht in #179 enthalten);
destruktive Tools bleiben so lange gesperrt, wie der Nutzer nicht ausdrücklich zustimmt.
OAuth-Auth ist im aktuellen Schritt nicht unterstützt.
> Architektur-Entscheidungen: docs/architecture/ADR-018-homeassistant-yaml-voice.md (YAML+Voice),
> docs/architecture/ADR-028-ha-dashboards-helpers-areas.md (Dashboards/Helpers/Areas/Szenen+Skripte),
> docs/architecture/ADR-047-addon-dependencies-feature-gating.md (Feature-Gating über das
MCP-Addon), docs/architecture/ADR-054-user-scoped-data-access.md (Per-User-Isolation für die
home-assistant-MCP-Zeile). Voraussetzungen für die HA-MCP-Sicherheit: #177 (Streamable-HTTP-
Transport im MCP-Addon) + #178 (Least-Privilege-Tool-Policy im MCP-Addon).
Iron Man-style AI assistant with weather, calendar, Tesla, and home automation.
\naiopta/addons/jarvis/.env.example to .env.local and configurenpm install| Feature | API | Auth Required |
|---------|-----|--------------|
| Weather | Open-Meteo | No |
| Calendar | Google Calendar | API Key |
| Tesla | Fleet API | OAuth Token |
| Home Assistant | REST API | Long-Lived Token |
| Morning Briefing | Aggregates all | Per-service |
### Weather
```
GET /api/jarvis/weather?lat=52.52&lon=13.40&forecast=true
```
### Calendar
```
GET /api/jarvis/calendar?today=true
GET /api/jarvis/calendar?start=2026-01-01&end=2026-01-07
```
### Tesla
```
GET /api/jarvis/tesla # List vehicles
GET /api/jarvis/tesla?vehicleId=123 # Vehicle status
POST /api/jarvis/tesla # Send command
{ "vehicleId": "123", "action": "wake" }
```
Actions: wake, lock, unlock, honk, flash, climate_on, climate_off, charge_start, charge_stop
### Home Assistant
```
GET /api/jarvis/home-assistant # All entities
GET /api/jarvis/home-assistant?entityId=light.living_room
POST /api/jarvis/home-assistant
{ "entityId": "light.living_room", "service": "toggle" }
```
### Morning Briefing
```
GET /api/jarvis/briefing
```
| Variable | Default | Description |
|----------|---------|-------------|
| WEATHER_DEFAULT_LAT | 52.5200 | Default latitude (Berlin) |
| WEATHER_DEFAULT_LON | 13.4050 | Default longitude (Berlin) |
| GOOGLE_CALENDAR_API_KEY | — | Google API key |
| GOOGLE_CALENDAR_ID | — | Calendar ID |
| TESLA_ACCESS_TOKEN | — | Tesla OAuth token |
| HOMEASSISTANT_URL | — | HA instance URL |
| HOMEASSISTANT_TOKEN | — | HA long-lived token |
This is a pure addon — zero changes to Aiopta core. Each service gracefully degrades when unconfigured (returns empty data).
\nGOOGLE_CALENDAR_API_KEY and GOOGLE_CALENDAR_ID.Die Bedienoberflaeche der LayerY-Druckzentrale — in Aiopta. Auftraege des
eigenen Slice-Dienstes ansehen, die Preisgrundlage lesen und einen Auftrag neu
schneiden lassen, ohne zweite Oberflaeche und ohne zweite Anmeldung.
Issue: addons#1229. Vorbedingung: addons#1195 (Eigentuemer und
Sichtbarkeit, im Slice-Dienst umgesetzt am 10.08.2026).
Der Slice-Dienst bleibt ein eigener Dienst. Nicht aus Bequemlichkeit:
OrcaSlicer-CLI, das Profil-Repository (ein Git-Klon mit Nutzerprofilen) und
die Auftragsablage passen nicht in einen Next.js-Container.
| | bleibt im Slice-Dienst | liegt in diesem Addon |
| --- | --- | --- |
| Schneiden, Anordnen, G-Code | X | |
| Profilregister, Filament, Ablage | X | |
| G-Code-Nachbearbeitung (M486) | X | |
| Bedienoberflaeche | | X |
| Angebot, ERP-Anbindung | | X (noch nicht umgezogen, siehe unten) |
| Shop-/WooCommerce-Anbindung | | X (noch nicht umgezogen, siehe unten) |
| Eigentuemer und Sichtbarkeit | Durchsetzung | Darstellung |
Der Dienst hat heute 43 HTTP-Routen. Ein Addon, das sie weiterreicht, ist kein
Addon, sondern ein Reverse Proxy mit Aiopta-Auth — dann laege die Drucklogik
doch wieder in Aiopta, nur verteilt ueber Routenpfade statt ueber Module.
Dieses Addon ruft deshalb vier Dienstrouten.
Bewusst draussen: Vorschaubilder, G-Code-Auslieferung, 3MF- und
Quelldateien, Live-Protokoll. Beim G-Code ist das keine Bequemlichkeit — die
Dienstroute streamt bereits, und eine puffernde Aiopta-Route machte aus einem
40-MB-Strom einen 40-MB-Puffer.
Alles wird in der Oberflaeche gesetzt (Einstellungen → Addons → LayerY
Druckzentrale). Es gibt keine Datei, die von Hand zu pflegen waere, und
keine Vorgabe fuer irgendeinen Wirt.
| Einstellung | Pflicht | Bedeutung |
| --- | --- | --- |
| baseUrl | ja | Wurzel des eigenen Slice-Dienstes, ohne Pfad |
| grantSecret | einer von beiden | geteiltes Geheimnis fuer kurzlebige Grants (im Dienst: AIOPTA_GRANT_SECRET bzw. die Datei aus AIOPTA_GRANT_SECRET_DATEI) |
| apiToken | einer von beiden | Ersatzweg: das Dienst-Wort (SLICER_API_TOKEN bzw. SLICER_TOKEN_DATEI) |
Ist die Basis-URL oder jeder Zugang leer, antwortet jede Route mit503 druckzentrale_not_configured — und es geht kein Netzruf raus. Das
ist gemessen, nicht behauptet: tests/unit/route-contract.test.ts prueft, dassfetch in diesem Fall nicht einmal gerufen wird.
Der Fehler sieht harmlos aus und ist es nicht. addons/layery-druckzentrale
geht an jede Aiopta-Installation. Stuende hier ein Wirt als Vorgabe, riefe
der Server eines fremden Betreibers, der das Feld leer laesst, still den
Produktivdienst eines fremden Kunden auf. Drei Addons dieses Repos sind ueber
genau diese Falle gestolpert (spoolman #1226, erpnext #1220,octoprint-proxy #1215).
* Grant (empfohlen): das Addon stellt je Ruf einen kurzlebigen,
HMAC-signierten Ausweis aus (X-Aiopta-Grant, Audience
addon:layery-slicer, Laufzeit 120 s). Er traegt die Kennung des
angemeldeten Aiopta-Nutzers, und **nur so greifen Eigentuemer und
Sichtbarkeit des Dienstes je Aufrufer**.
* Dienst-Wort: das Addon schickt X-Slicer-Token. Der Dienst behandelt
jeden Traeger als Betreiber — der angemeldete Nutzer sieht damit alle
Auftraege.
Der Grant hat Vorrang, wenn beides gesetzt ist. Und die Oberflaeche schreibt
hin, welcher Weg gerade laeuft: eine Betreibersicht, die man fuer seine eigene
haelt, ist schlimmer als gar keine.
Das Grant-Format ist byte-genau das aus app/grant.py des Dienstes; der
Vergleichswert steht als gemessener Testvektor in tests/unit/grant.test.ts.
| Aiopta-Route | Methode | Bildet ab auf | Permission |
| --- | --- | --- | --- |
| …/jobs | GET | GET /jobs | addons/layery-druckzentrale/jobs/read |
| …/jobs/{id} | GET | GET /slice/{id} + GET /slice/{id}/dateien | addons/layery-druckzentrale/jobs/read |
| …/jobs/{id}/calculation | GET | GET /slice/{id}/kalkulation | addons/layery-druckzentrale/pricing/read |
| …/jobs/{id}/reslice | POST | POST /slice/{id}/neu | addons/layery-druckzentrale/jobs/reslice |
| …/quotes/{name} | GET | erpnext in-Prozess + wordpress (optional) | addons/layery-druckzentrale/quotes/read |
| …/quotes/{name}/pdf | GET | erpnext in-Prozess | addons/layery-druckzentrale/quotes/read |
| …/quotes/{name}/prices | POST | erpnext in-Prozess | addons/layery-druckzentrale/quotes/price |
| …/quotes/{name}/submit | POST | erpnext in-Prozess | addons/layery-druckzentrale/quotes/submit |
Die Preisgrundlage haengt an einer eigenen Berechtigung. Wer sehen darf,
was gerade druckt, darf deshalb noch nicht sehen, was es den Betrieb kostet:
die Aufstellung traegt Stundensaetze, Materialpreise und Aufschlaege, die
Auftragsliste nicht.
Die Angebotsstrecke lag in app/shop.py des Slice-Dienstes und ging von dort
ueber n8n-Webhooks (Workflows 07–11) an ERPNext. Der Dienst brauchte dafuer
eine Aiopta-Adresse und einen Agent-Key — einen Netzruf von aussen nach
innen. Die vier quotes-Routen loesen das ab.
Es gibt zwei uebliche Wege, ein fremdes Addon zu benutzen. Dieses Addon nimmt
den zweiten:
1. Rueckschleife — ein echter HTTP-Ruf auf die eigene Aiopta-Instanz, wie
seo-content → wordpress. Das haette den Netzruf nur nach innen
verschoben und einen weiteren installationsgebundenen Wert gebraucht (die
eigene Basis-Adresse).
2. In-Prozess — die Client-Bibliothek von erpnext wird direkt benutzt,
wie chat die von browser benutzt. Kein zweiter Netzweg, kein zweites
Envelope, ein Zugang.
Der Preis, offen benannt: die Routen von erpnext laufen dabei nicht mit,
und deren Permission addons/erpnext/quotation/read wird nicht geprueft.
Die Autorisierung liegt vollstaendig bei den Routen dieses Addons. Sie sind
deshalb nicht schwaecher gestuft als das ERP-Gegenstueck: quotes/price undquotes/submit stehen auf highest. Wer src/lib/quote-bridge.ts aendert,
aendert eine Berechtigungsgrenze.
item_codeBei LayerY nummeriert der item_code nur durch (LaY-3D-3440-01,LaY-3D-3440-02) und sagt nichts darueber, welche Datei die Zeile meint. Zwei
Positionen mit vertauschten Preisen faenden darueber nicht auseinander; am
06.08.2026 hat genau diese Fehlerklasse im Betrieb 141,83 EUR statt 36,98 EUR
ergeben. addons/erpnext nimmt seit 0.3.0 die Unterzeile (items[].name) an
und laesst sie den item_code schlagen — dieses Addon liefert ausschliesslich
sie, und der item_code wird als Schluessel gar nicht erst angenommen.
Weil der Betreiber den Hash nicht kennt, nimmt die Route auch source (den
Namen der Kundendatei) und loest ihn gegen den frisch gelesenen Beleg auf
(src/lib/position-match.ts, Portierung von shop.position_fuer_quelle).
Null oder mehrere Treffer sind ein lauter Fehler — geraten wird nicht.
Dieses Addon fuehrt keine ERP-Adresse und kein ERP-Token im eigenensettingsSchema. Beides bleibt beim erpnext-Addon. Waeren sie hier noch
einmal gefuehrt, gaebe es dieselben Zugangsdaten an zwei Orten mit zwei
Rotationszeitpunkten.
Dabei greift ein eigener Waechter. Als diese Strecke entstand, fieladdons/erpnext bei leerer Einstellung still auf eine feste ERP-Adresse
zurueck (addons#1220); wer dessen getErpSettings() ungeprueft benutzte,
erbte die Falle. Am 11.08.2026 wurde das drueben behoben (PR #1223,erpnext auf 0.6.0, Bruch).
requireErpnextConfig() bleibt trotzdem — aus zwei Gruenden, die von der
fremden Fassung unabhaengig sind:
1. Fail-closed an der eigenen Grenze. Die Kante nennt minVersion
0.3.0; auf einer Instanz mit einer aelteren Fassung greift der alte
Rueckfall weiterhin. Die Zusage „ohne ERP-Adresse geht nichts ans Netz"
darf nicht davon abhaengen, welche Fassung des Nachbarn installiert ist.
2. Die Antwort kommt ohne Modulladen zustande. 503
erpnext_not_configured faellt, bevor das ERP-Modul importiert ist —
und der Test pinnt, dass dabei kein einziger fetch laeuft.
wordpress, und die Kante ist optionalbestellung gehoert nicht ins ERP-Addon — das wurde in addons#1213
begruendet entschieden (die Route existiert im wordpress-Addon bereits,
Shop-Zugangsdaten laegen sonst an einem zweiten Ort, und die Shop-Adresse
waere ein zweiter installationsgebundener Wert). Der Aufrufer soll den Block
selbst holen — dieses Addon ist dieser Aufrufer.
Die Kante ist optional: true, weil Abnahmekriterium 1 einen Betrieb ohne
WooCommerce verlangt. Deshalb wirft dort nichts: ein fehlender Shop darf
das Lesen eines Angebots nicht scheitern lassen. Stattdessen kommt ein
benannter Zustand mit, und die Oberflaeche zeigt ihn:
| Zustand | Heisst |
| --- | --- |
| ok | Bestellung gelesen |
| no_reference | das Angebot zeigt auf keine WooCommerce-Bestellung (po_no ohne WC-<id>) |
| unavailable | das wordpress-Addon ist nicht installiert — zulaessig |
| not_configured | installiert, aber leer eingerichtet; es ging nichts ans Netz |
| failed | der Shop hat nicht geantwortet — ob es die Bestellung gibt, ist unbekannt, nicht „keine" |
Diese fuenf zu einem null zusammenzufassen waere der teuerste Kurzschluss
dieser Strecke: „kein Shop installiert" und „Shop antwortet gerade nicht"
verlangen vom Betreiber Entgegengesetztes.
Der Sendeweg fehlt bewusst, und der Grund hat sich waehrend dieser Scheibe
geaendert — das ist wichtig genug, um es hinzuschreiben statt es zu
glaetten.
Als die Scheibe begann, war der Sendeweg von addons/erpnext (v0.3.0)
nachweislich unehrlich: er reichte einen Entwurf nicht vorher ein, kannte die
Frage nach dem Postausgang nicht, und die Route antwortete sent: true,
sobald der Aufruf kein Nicht-2xx lieferte. **Am 11.08.2026 wurde genau das
behoben und gemerged** (addons#1212 / PR #1219; erpnext steht seither auf
0.6.0). Der alte Grund ist damit weg.
Der neue Grund ist die Reihenfolge selbst. Senden ist der einzige Weg, dessen
Fehler den Kunden erreicht; ein falsches „verschickt" faellt erst auf,
wenn der Kunde nicht antwortet. Ein solcher Weg wird nicht am Ende einer
Scheibe nachgeschoben, weil die Gegenseite gerade gruen geworden ist. Er
bekommt eine eigene Scheibe mit
* eigener Berechtigung (quotes.send, highest),
* eigenen Tests gegen die neue Antwortform
({sent, grund, submitted, docstatus}) statt gegen die alte,
* und einer eigenen Anzeige fuer sent: false, die dem Betreiber sagt, dass
er umschwenken muss statt es spaeter nochmal zu versuchen.
Genau so steht es in PLAN-n8n-abloese.md: Senden kommt zuletzt, und
einzeln. Bis dahin laeuft der Versand unveraendert ueber den bisherigen Weg —
es geht nichts verloren, es wird nur nichts Neues behauptet.
In der Oberflaeche steht der Sende-Knopf deshalb da und ist aus, mit
Grund. Ihn wegzulassen saehe aus wie vergessen.
| Situation | Status | code |
| --- | --- | --- |
| nichts eingestellt (kein Netzruf) | 503 | druckzentrale_not_configured |
| Basis-URL unbrauchbar (kein Netzruf) | 503 | druckzentrale_invalid_base_url |
| Zugang abgelehnt | 502 | druckzentrale_auth_failed |
| Grant deckt die Route nicht ab | 502 | druckzentrale_grant_scope |
| Dienst nicht erreichbar | 502 | druckzentrale_unreachable |
| Auftrag unbekannt oder verborgen | 404 | job_not_found_or_hidden |
| Preisgrundlage noch nicht belastbar | 409 | calculation_not_ready |
| Schnitt begruendet abgelehnt (nichts gestartet) | 409 | reslice_rejected |
| Schnitt-Ausgang unklar | 409 | reslice_unclear |
Drei davon verdienen einen eigenen Absatz:
\njob_not_found_or_hidden heisst nicht „geloescht". Der Slice-Dienst tarnt
eine Sichtbarkeitsverweigerung absichtlich als 404 mit dem Textunbekannte job_id, damit die Existenz eines fremden Auftrags nicht
durchscheint. Dieses Addon loest die Zweideutigkeit nicht auf — das waere
genau das Leck, das die Tarnung verhindern soll.
calculation_not_ready ist keine leere Preisgrundlage. Ist ein Auftrag
noch nicht so weit, antwortet der Dienst mit 200 und einem Feld fehler
statt einer Kalkulation. Ein Client ohne diese Pruefung zeigte eine leere
Aufstellung — und die liest sich wie „kostet nichts".
reslice_unclear wird nicht wiederholt. Ein Schnitt ist nicht idempotent:
er belegt Rechenzeit, schreibt Dateien in die Auftragsablage und loest die
bisherigen Artefakte ab. Bleibt der Ausgang unklar, sagt die Route genau das —
samt Zeitpunkt als Ankerwert fuer die Nachschau — und schneidet nicht nach.
POST …/reslice nimmt nur die Felder an, die der Dienst als Ueberlagerung
kennt: anweisung, filament_spool_id, filament_id, prozess_profil,prozess_werte, profil_overrides, material, color, quality,ausfuehrungsort, nur_dateien, ohne_dateien, mengen_overrides,projektquelle, modus.
source, order_id und kunde fehlen dort absichtlich — sonst liesse
sich ein Auftrag im Nachhinein einem anderen Kunden zuschreiben. Eine
Sperrliste muesste jedes kuenftige gefaehrliche Feld kennen; die Positivliste
kennt nur die harmlosen.
Beides kommt aus dem Dienst (addons#1195):
eigentuemer = { mandant, nutzer, quelle }, quelle ∈ grant | token | lokalsichtbarkeit ∈ privat | mandant | betriebFuer Auftraege von vor dem 10.08.2026 gibt es keinen Eigentuemer. Dann
zeigt die Oberflaeche den eigentuemer_vermerk des Dienstes und raet keine
Zuordnung dazu.
Und: die Auftragsliste ist gefiltert. Der Dienst laesst nicht sichtbare
Auftraege weg, ohne sie zu erwaehnen. Die Antwort traegt deshalbfilteredByService: true, und die Seite schreibt es hin — „das sind alle
Auftraege" waere eine Behauptung, die der Dienst nie aufgestellt hat.
addons#1294)Der Konfigurationsausschnitt zeigt jeden Regler als **eine Zeile mit einem
Wert**. Fuer eine Zahl ist das richtig. Der Reglerqualitaet.stabilitaetsstufen traegt aber eine Tabelle — je
Festigkeitsstufe die Prozesswerte, die sie erzwingt —, und als Zeile bliebe
davon [{"stufe":"dekorativ","wall_loops":null,…}] uebrig. Nicht falsch, nur
keine Auskunft: die Aussage dieser Tabelle ist eine Leiter.
app/faehigkeiten.py im Dienst sagt woertlich, warum ein Addon sie ueberhaupt
sehen darf: wer dem Kunden „Belastbar" zur Wahl stellt, muss sagen koennen,
was Belastbar bedeutet — sonst zeigt er eine Zusage an, die er nicht kennt.
Deshalb steht die Leiter zusaetzlich zur Reglerzeile: die Zeile sagt, dass
es den Regler gibt und ob dieser Zugang ihn setzen darf; die Leiter sagt, was
er bedeutet.
Stabilitaet ist eine Untergrenze. Die gewaehlte Stufe darf Waende und
Fuellung erhoehen, nie senken. Der Dienst lehnt eine absteigende Tabelle beim
Speichern ab und bleibt die Instanz; dieses Addon **entscheidet nichts und
rechnet nichts nach**. Findet es trotzdem einen Bruch (aeltere Fassung des
Dienstes, von Hand geschriebenes betrieb.json, Wert aus einer
Umgebungsvariablen), ist das ein Befund und steht als Fehler da — in einer
sortierten Tabelle saehe er aus wie vier normale Zeilen.
Was hier nicht passiert:
\n* Keine Zahlen im Addon. Nirgends steht „belastbar heisst 5 Waende". Das
waere ein installationsgebundener Wert — und die zweite Wahrheit: der
Betreiber darf die Tabelle drehen, und ein Addon mit eigener Fassung wuerde
ihm die alte Zusage bestaetigen. Ein Testfall misst dafuer den Quelltext.
* Keine neue Berechtigung. Gelesen wird der Block, der ueber
addons/layery-druckzentrale/jobs/read ohnehin schon kommt.
* Kein stiller Rueckfall. „Der Regler ist in dieser Sicht nicht
freigegeben", „der Dienst hat nichts geschickt" und „die Tabelle ist leer"
sind drei Auskuenfte und sehen verschieden aus. Eine leere Anzeige fuer alle
drei hiesse „dieser Betrieb erzwingt nichts" — und das ist die einzige der
drei, die beruhigt.
addons#1308)Am 12.08.2026 um 23:07:23 nahm ein docker restart slicer-api einen 42
Sekunden alten, lebenden Lauf mit. RestartCount=0, kein OOM — ein
gewollter Neustart von Hand. Die Neustartsperre des Slice-Dienstes haette
gehalten; sie wurde nur nicht gefragt, denn sie sitzt in run.sh, unddocker restart, docker stop und docker compose gehen daran vorbei.
In dieser Oberflaeche stand danach dieselbe rote Ueberschrift wie bei einem
Lauf, der an der Geometrie gescheitert ist: *„Der Dienst meldet einen Fehler
zu diesem Lauf"*. Beide verlangen aber verschiedene Handgriffe — der eine ein
anderes Modell oder Material, der andere nur einen neuen Anlauf **und die
Frage vor dem naechsten Neustart**. So sah der teure Fall aus wie ein
Modellproblem.
Eingeordnet wird ueber das Feld status.abbruch_art des Dienstes
(app/main.py, ABBRUCH_ART_NEUSTART), nicht ueber den deutschen Satz
daneben. Ihn nach dem Wort „Neustart" abzusuchen waere verlockend — er steht
ja da —, aber beim naechsten Umformulieren im Dienst zeigte diese Oberflaeche
etwas Falsches an, und das faellt niemandem auf: der Satz sieht weiter richtig
aus, nur die Einordnung stimmt nicht mehr. Dieselbe Regel wie beischnittabbrueche[].art (addons#1289, abbruchgrund.ts).
Ein Lauf ohne das Feld — also einer von vor addons#1308 — gilt
ausdruecklich als nicht durch einen Neustart abgebrochen. Eine geratene
Einordnung waere hier schlechter als gar keine: sie stuende mit demselben
Nachdruck da wie eine gemessene.
Der Satz des Dienstes bleibt sichtbar — er ist der Beleg; die Einordnung
darueber ist die Auskunft. Der Handgriff nennt den einen Schritt, der dieselbe
Frage auf jedem Weg beantwortet:
docker exec slicer-api python3 /root/slicer/app/neustartsperre.pyaddonDependencies ist ein Record<addonId, …>, kein Array. Einerequired-Kante auf ein Addon, das auf der Zielinstanz fehlt, ergibtaddon_dependencies_unmet und HTTP 409 — das Addon waere dort nicht
installierbar.
| Addon | Kante | Warum |
| --- | --- | --- |
| erpnext | optional >=0.3.0 | In 0.2.0 von required gelockert — Begruendung unten. |
| wordpress | optional >=1.2.0 | WooCommerce ist ein Bestellkanal, nicht der einzige. Ein Betrieb, der nur ueber ERP anbietet, muss installieren koennen (Abnahmekriterium 1). |
| spoolman | optional >=0.2.0 | Der Filament-Bestand bleibt laut Schnitt im Slice-Dienst; dieses Addon liest ihn von dort, nicht aus Spoolman. |
| octoprint-proxy | optional >=2.0.0 | Die Strecke zum Drucker haengt am Slice-Dienst, nicht an diesem Addon: der Dienst spricht den Sync-Proxy selbst an. |
Alle vier Kanten degradieren nach ADR-047 transparent mit maschinenlesbarem
Grund (optional-dependency-missing) — das ist fuer eine Ansicht das
richtige Verhalten, eine harte Kante waere es nicht.
erpnext von required auf optional gewechselt istIn 0.1.0 war die Kante hart, mit der Begruendung „es gibt keinen zweiten
ERP-Weg". Der erste Halbsatz stimmt; der Schluss daraus war falsch. Zwei
Dinge wurden verwechselt:
* Dass die Angebotsstrecke nur ueber erpnext laeuft — richtig.
* Dass dieses Addon ohne ERP nutzlos waere — falsch. Auftraege ansehen,
die Preisgrundlage lesen und neu schneiden sprechen ausschliesslich mit dem
Slice-Dienst. Das war der gesamte Inhalt von 0.1.0, und es funktioniert auf
einer ERP-freien Instanz vollstaendig.
Was die harte Kante tatsaechlich bewirkt hat: nach ADR-047 endet eine
unerfuellte required-Kante in addon_dependencies_unmet und HTTP 409.
Die Druckzentrale waere damit auf jeder Instanz ohne erpnext
uninstallierbar gewesen — und erpnext ist derzeit nirgends
installiert.
Der zweite Grund ist ein Widerspruch im eigenen Code: waere die Kante hart,
koennte der Fall „erpnext fehlt" gar nicht eintreten, und die Codeserpnext_unavailable / erpnext_not_configured waeren toter Code. Genau
die Degradierung, die dieses Addon sorgfaeltig baut und testet, waere
unerreichbar. Mit optional gilt stattdessen:
* ohne erpnext laufen die jobs-Routen und die Oberflaeche weiter;
* die vier quotes-Routen antworten 503 erpnext_unavailable mit
sprechendem Grund, statt dass gar nichts installierbar ist.
druckzentrale-tools (read-only)job_list, job_get, job_artifacts.
Bewusst kein schneidendes Werkzeug: ein Agent, der bei unklarer Antwort
noch einmal ruft, laesst denselben Auftrag ein zweites Mal rechnen. Der
schneidende Pfad laeuft ausschliesslich ueber die API-Route mit eigener,
hoechster Trust-Stufe. Die Preisgrundlage ist ebenfalls nicht exponiert: sie
haengt an einer eigenen Berechtigung.
Der Server ist ohne Env handshake-faehig (Conformance C3) und faellt ohneAIOPTA_CONFIG_BASEURL fail-closed aus.
Drei getrennte Achsen, die gern verwechselt werden:
\n1. ADR-062 (trusted | standard | restricted) — instanzweit, admin-gesetzt,
steht nicht im Manifest, durchgesetzt ueber isMethodAllowedForTrust.
2. capabilityDeclarations[].tier (standard | elevated | highest) — die
deklarative Absicht dieses Addons.
3. Die Permission selbst.
Deshalb liegt der Schnittpfad auf POST: nur ein mutierendes Verb wird aufrestricted abgewiesen. Die Versuchung war hier greifbar — eine „Neu
schneiden"-Verknuepfung haette sich als GET viel bequemer in eine
Tabellenzeile setzen lassen und den Sandbox-Schutz still ausgehebelt.
Ehrliche Liste, damit niemand danach sucht:
\n* Senden (n8n-Workflow 11). Bewusst nicht verdrahtet — siehe oben. Die
Vorbedingung (addons#1212) ist seit dem 11.08.2026 erledigt; es fehlt
die eigene Scheibe, nicht die Gegenseite. Der Versand laeuft bis dahin
unveraendert ueber den bisherigen Weg.
* Das Mailkonto-Feld erpMailAccount anzeigen. GET /quotation/{name}
von erpnext traegt es seit 0.4.0 (addons#1213, gemergt am 11.08.2026)
als {outgoing, grund, konto} mit dreiwertigem outgoing. Diese
Ansicht liest es noch nicht — sie wurde gegen 0.3.0 geschnitten. Nachzuholen
ist genau eine Sache, und sie ist nicht kosmetisch: false („es gibt
keines") und null („nicht feststellbar", meist HTTP 403 auf
Email Account) duerfen in der Anzeige nicht gleich aussehen. Gehoert
in dieselbe Scheibe wie Senden.
* Ein Angebot ANLEGEN und Angebote SUCHEN. erpnext kann heute lesen und
aendern; Quotation anlegen (n8n-Workflow 01) und ueber Kriterien suchen
(02, 04) fehlen dort. Das gehoert zur Ablose der Orchestrierer.
* lost (Kundenentscheidung). Die Route existiert im erpnext-Addon,
aber der Entscheidungsweg haengt an den WooCommerce-Bestaetigungen
(decision-ack, lost-ack) aus dem Plugin Layery-FileIntake, die im
wordpress-Addon noch nicht abgebildet sind.
*Die Regler im Slice-Dienst abbauen (integration.aiopta_url,
aiopta_agent_key).** Abnahmekriterium 3. Sie liegen im Dienst-Repo, nicht
hier. Sie fallen erst, wenn die Angebotsstrecke ueber dieses Addon im
Betrieb bestaetigt ist — sie vorher zu ziehen hiesse, den bisherigen Weg
abzuschneiden, bevor der neue gemessen ist.
* Einen neuen Auftrag anlegen. POST /slice ist beim Dienst gemessen
nicht grant-schreibbar (die Pruefung verlangt path.startswith("/slice/"),
und /slice faellt durch). Ein Anlegen ueber das Addon braucht also erst
eine Aenderung im Dienst.
* Konfiguration und Faehigkeiten des Dienstes (/dashboard-api/konfiguration,
Profilregister, Filament, Druckerstatus). Das ist die geplante Route
…/capabilities und fasst vier Dienstrouten zusammen; sie gehoert in
denselben Schritt wie das Angebot.
* Die sechs n8n-Orchestrierer (00–05) abloesen. Reihenfolge laut Issue:
erst der Umzug der Angebots- und ERP-Logik, dann die Orchestrierer.
Workflow 00 kommt zuletzt — er gibt Kundendateien auf dem Webserver zur
Loeschung frei.
* Eine signierte attestation.json. Signiert wird ausschliesslich im
Auftrag ci/Jenkinsfile.addonsign mit der Credential
aiopta-addon-signing-key; der Schluessel liegt weder im Repo noch bei
einem Entwickler. Bis dahin traegt das Addon einen ticketgebundenen Eintrag
in BEKANNTE_LUECKEN (addons#1002).
\n⚠️ **DEPRECATED — merged into the canonical
crmaddon (ADR-008 addon-consolidation,issue #491 / epic #490).**
crmis the durable, full CRM that ADR-015 already builds on top of thisCRM-lite. lead-gen remains functional and data-preserving until its sunset on 2026-12-31 — no
endpoint is removed and no row is copied or deleted. The Alt-ID redirect is expressed through the
addon metadata (
replacedBy: crm,sunset,settingsPagePath: /addons/crm) so the Marketplace andSettings-Hub point at the successor, and — at the record level — through
crm's
getContactByLeadEmail, which resolves an old lead-gen lead identity (by email) to the migrated CRMcontact. The lossless consolidation path is
crm's per-userimportLeadsreconcile(
POST /api/v1/addons/crm/import/leads), which reads this addon's own scoped store and never mutatesthe
lead_gen_*tables. See the PR for #491 for the license/pricing/permission review.
A Money-Stufe-1 addon: a lightweight CRM plus cold-outreach engine. Capture and qualify leads,
scrape/enrich them via an Aiopta-managed container, draft personalized messages through the Aiopta
AI gateway, and send them under mandatory anti-spam guardrails.
This addon orchestrates existing Aiopta building blocks the same way seo-content anddropshipping do (ADR-015):
- AI message generation → the Aiopta gateway (@/lib/gateway, chatCompletionWithFallbacks). There is
no direct LLM/provider call anywhere in the addon.
- Scraping / enrichment → an Aiopta-managed container (ADR-009), reached only via
getContainerAddonInternalUrl("lead-gen") — never a hard-coded host.
- Sending → an SMTP/ESP interface that reads config from Aiopta addon-config — **no secret in the repo
or logs**.
Cold outreach is dangerous if it can blast. This addon makes a careless mass-send **structurally
impossible. Three guardrails are enforced in src/lib/sender.ts and are not optional**:
1. Explicit confirmation. POST /sequences/:id/send refuses to send unless the request body
contains confirm: true. Without it the call returns 400 before any transport is opened — no
accidental blast.
2. Suppression / opt-out check. Every recipient is checked against the suppression list
(/suppression). A suppressed / opted-out address is never sent to — it is skipped and reported.
This is the source of truth for honoring unsubscribes; add an address there and it is dead to the
sender forever.
3. Rate limits. A small per-run cap and a daily cap (both configurable in addon-config,
with conservative defaults — 25/run, 200/day) bound how many messages can go out. Anything over
the remaining quota is deferred (rate-limited), not sent.
The ordering is strict and pure (planSend): drop invalid emails → drop suppressed → apply the
remaining-quota cap. It is unit-tested without any SMTP/DB so the guarantee can't silently regress
(tests/unit/sender.test.ts).
\nMass-send / bulk outreach without explicit owner approval is not supported. These guardrails are
a guardrail, not a setting to switch off. Sending also requires SMTP/ESP config to be present
(missing → 400), so the addon can never email through an unconfigured transport.
The CRM is per-user, not a shared catalog. Contacts, sequences (+ their steps), the
suppression / opt-out list and the daily send-log all carry user_id and are read/written only
through scopedStore(auth.id) / WHERE user_id = ?. The server stamps the owner from the session
(a client-supplied user_id is ignored), and a foreign contact/sequence id returns 404 (not the
row, not 403). Two users may track the same email independently (UNIQUE(user_id, email)).
Critically, suppression and the rate-limit are per user: one user's opt-out list cannot gag
another user's outreach, and one user's sent volume cannot consume another's daily quota.
Stored via Aiopta addon-config for the lead-gen addon; secret-looking keys (*_PASS, *_API_KEY) are
persisted with is_secret = 1. Two owner decisions are parked in docs/OPEN-DECISIONS.md
(lead-scraper-image, lead-gen-email-config).
lead-gen-email-config)| Key | Meaning | Default |
|-----|---------|---------|
| ESP_PROVIDER | smtp (wired) or sendgrid/mailgun/postmark/resend (declared) | smtp |
| SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS | SMTP connection (provider = smtp) | — / 587 / — / — |
| SMTP_SECURE | "true" for implicit TLS | false |
| SMTP_FROM (or ESP_FROM / FROM) | From address (required for any send) | — |
| ESP_API_KEY | ESP API key (provider ≠ smtp) | — |
| SEND_PER_RUN_LIMIT | per-run rate cap | 25 |
| SEND_DAILY_LIMIT | rolling-24h rate cap | 200 |
Until email is configured, /status reports email.configured: false and any send returns a clear
400. No secret is ever written to the manifest or surfaced by /status (only booleans, the provider
id, and the from-domain).
lead-scraper-image)Declared as a container in addon.json / src/manifest.ts:
image: registry.langkau.info/aiopta/lead-scraper:latest\ninternalPort: 8080\nhealthPath: /health\nenvSchema: ENRICHMENT_PROVIDER, ENRICHMENT_API_KEY, SCRAPER_USER_AGENT, SCRAPER_RATE_LIMITenvSchema declares only the names of the keys the container needs (enrichment-provider
credentials); the values come from Aiopta addon-config, never the manifest. The image is owner-built —
until it is published, /status reports scraper.provisioned: false and /enrich (scrape/enrich)
returns a clear 503. The addon never falls back to a default host.
Base: /api/v1/addons/lead-gen (all routes auth-gated; agent capability lead-gen/*).
| Goal | Method + path | Body |
|------|---------------|------|
| Status (scraper + email + gateway + pipeline + limits) | GET /status | — |
| List contacts | GET /contacts?stage=new | — |
| Create / upsert a contact | POST /contacts | { "email": "…", "name": "…", "company": "…" } |
| Read / edit / delete a contact | GET|PUT|DELETE /contacts/:id | edit: { "stage": "…", "tags": […] } |
| Pipeline board | GET /pipeline | — |
| Move a contact's stage | PUT /pipeline | { "contactId": 1, "stage": "contacted" } |
| List sequences | GET /sequences | — |
| Create a sequence | POST /sequences | { "name": "…", "goal": "book a demo" } |
| Draft messages (via gateway) | POST /sequences/:id/generate | { "stage": "new" } or { "contactId": 1 } |
| Send drafts (guarded) | POST /sequences/:id/send | { "confirm": true, "messages": [{ "contactId": 1, "subject": "…", "body": "…" }] } |
| Suppression list | GET /suppression | — |
| Add an opt-out | POST /suppression | { "email": "…", "reason": "unsubscribe" } |
| Scrape / enrich (container) | POST /enrich | { "query": "…" } · { "contactId": 1 } · { "email": "…" } |
| Dashboard widget (flat) | GET /widget | — |
new → contacted → replied → qualified → won/lost. won/lost are terminal (a closed deal can't be
re-opened by a move — delete + recreate instead). Moving to replied stamps the reply timestamp, which
drives the reply-rate shown on the page and widget. The stage-machine (canTransition) is pure and
unit-tested.
- Page (Money section, /addons/lead-gen): tabs Leads (table + add/scrape), Pipeline
(per-stage columns with move buttons), Sequences (create → generate drafts → edit → **send with a
required confirm checkbox), Suppression** (opt-out list). A status banner shows gateway/scraper/
email readiness and the active rate limits.
- Widget (lead-gen.pipeline): open leads, reply-rate, won, suppression size, scraper + email
readiness.
- AI via gateway only. src/lib/sequencer.ts builds the prompt and calls
chatCompletionWithFallbacks — no provider fetch. A test stubs global fetch and asserts it is
never called during generation.
- Scraper via the container-service. src/lib/scraper.ts resolves the base URL with
getContainerAddonInternalUrl("lead-gen"); absent → 503 (tested), present → calls the internal
/scrape and /enrich endpoints.
- Sender is an interface with guardrails. src/lib/sender.ts reads SMTP/ESP from addon-config,
enforces confirm + suppression + rate-limit, and records each send for the daily cap.
- CRM owns its tables. src/lib/crm-store.ts creates lead_gen_contacts, lead_gen_suppression,
lead_gen_sequences, lead_gen_sequence_steps (and the sender's lead_gen_send_log) in install()
and drops them in uninstall() via Aiopta core's getDb().
addons/lead-gen/tests/unit/ (run with the manifest-route-sync test):
- manifest.test.ts — manifest validity, namespaced endpoints, page + widget, container present,
least-privilege skills (only lead-send carries /send), no secret/host in the manifest.
- crm-store.test.ts — the pure stage-machine + email/contact validation.
- sender.test.ts — the anti-spam guarantees: planSend never includes a suppressed contact and
enforces per-run/daily caps; sendBatch rejects without confirm, rejects when unconfigured, and
with confirm never delivers to a suppressed contact and caps the batch.
- sequencer.test.ts — generation routes through @/lib/gateway, never a direct provider fetch.
- scraper.test.ts — reached only via getContainerAddonInternalUrl; container-absent → 503.
wsl -e bash -lc 'cd /mnt/c/Users/Patrick/IdeaProjects/Antigravity/aiopta && \\\n docker run --rm -v "$PWD":/app -w /app node:22-slim \\\n node node_modules/vitest/vitest.mjs run \\\n tests/unit/extensions/manifest-route-sync.test.ts addons/lead-gen/tests/unit'Routing over the Core provider catalog, subscriptions and monitoring as an installable addon.
\nmanifest-routing/addons/manifest-routingDieses Addon benötigt folgende Secrets/Provider-Konfiguration (Settings → Credentials bzw. Provider-Store, nie in addon.json):
\nOPENAI_CLIENT_SECRETProvider, Modelle und API-Keys werden ausschließlich vom Core unter/settings#llm-providers beziehungsweise /api/v1/llm-providers verwaltet.
Manifest Routing liest den Core-Provider-Katalog und referenziert dessen Provider- und Modell-IDs
in Routing-Regeln; das Addon besitzt keine eigene Provider-CRUD-Oberfläche.
| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/manifest-routing |
| GET, POST, DELETE | /api/v1/addons/manifest-routing/failed-requests |
| GET | /api/v1/addons/manifest-routing/health-check |
| GET, POST, DELETE | /api/v1/addons/manifest-routing/notifications |
| POST | /api/v1/addons/manifest-routing/oauth |
| DELETE | /api/v1/addons/manifest-routing/rule/[id] |
| GET | /api/v1/addons/manifest-routing/stats |
| GET | /api/v1/addons/manifest-routing/status |
| GET, POST, PUT, DELETE | /api/v1/addons/manifest-routing/subscriptions |
| GET, POST | /api/v1/addons/manifest-routing/zai |
", "byteSize": 1667 } } }, { "id": "marketing-ads", "uuid": "f1030d66-e21a-4546-8085-1ea9840bdf6d", "name": "Marketing & Ads (Affiliate-Tracking + Google/Meta Kampagnen + KI-Creatives)", "version": "1.0.3", "description": "Per-User Marketing: Ad-Kampagnen (Google/Meta) mit Budget & ROAS, Affiliate-Tracking mit Klick-/Conversion-Zählern und KI-Creative-Prompts. Plattform-Spend/Revenue fließen über einen injizierbaren, per-User BYOK Fetch-Seam (nie hartcodiert); KI-Creatives hinter einem LLM-Gateway-Seam mit graceful Degradation. Lokale SQLite ist die Quelle der Wahrheit (ADR-054).", "author": "Aiopta", "icon": "📣", "capabilities": [ "marketing", "ads", "campaigns", "google", "meta", "affiliates", "creatives", "budget", "roas" ], "tags": [], "download": "/artifacts/marketing-ads-1.0.3.zip", "sha256": "19474dbd3ade5e29c824bb38d2e9cdabd4a9d67f3e25301ab7f8fba70580840d", "size": 121571, "page": { "id": "marketing-ads-page", "path": "/addons/marketing-ads", "name": "Marketing & Ads", "icon": "📣", "section": "Money", "component": "@addons/marketing-ads/src/components/MarketingAdsPage" }, "deprecated": false, "endpoints": [ "/api/v1/addons/marketing-ads/campaigns", "/api/v1/addons/marketing-ads/campaigns/:id", "/api/v1/addons/marketing-ads/affiliates", "/api/v1/addons/marketing-ads/affiliates/:id", "/api/v1/addons/marketing-ads/affiliates/:id/click", "/api/v1/addons/marketing-ads/affiliates/:id/convert", "/api/v1/addons/marketing-ads/creatives", "/api/v1/addons/marketing-ads/creatives/:id", "/api/v1/addons/marketing-ads/stats" ], "skills": [ { "name": "marketing-ads-read", "displayName": "Marketing & Ads: Kampagnen, ROAS & Affiliates lesen", "description": "Listet Ad-Kampagnen (Google/Meta) mit Budget/Spend/Revenue/ROAS, Affiliate-Links mit Klick-/Conversion-Zählern und KI-Creatives für den Nutzer. Reiner Lesezugriff — legt nichts an.", "permissions": [ "addons/marketing-ads/campaigns", "addons/marketing-ads/affiliates", "addons/marketing-ads/creatives", "addons/marketing-ads/stats" ], "endpoint": "/api/v1/addons/marketing-ads/stats", "scripts": [] }, { "name": "marketing-ads-manage", "displayName": "Marketing & Ads: Kampagnen & Budget verwalten", "description": "Legt Ad-Kampagnen (Google/Meta) an oder entfernt diese und setzt Status/Budget/Spend/Revenue (per-User gebucht). ROAS wird aus lokaler Spend/Revenue berechnet.", "permissions": [ "addons/marketing-ads/campaigns" ], "endpoint": "/api/v1/addons/marketing-ads/campaigns", "scripts": [] }, { "name": "marketing-ads-affiliates", "displayName": "Marketing & Ads: Affiliate-Links verwalten", "description": "Legt Affiliate-/Partner-Links an, zeichnet Klicks/Conversions auf (per-User gebucht) und entfernt diese.", "permissions": [ "addons/marketing-ads/affiliates" ], "endpoint": "/api/v1/addons/marketing-ads/affiliates", "scripts": [] }, { "name": "marketing-ads-creatives", "displayName": "Marketing & Ads: KI-Creatives generieren", "description": "Erstellt KI-Creative-Prompts (Google/Meta) und generiert Copy über das LLM-Gateway (graceful Degradation auf einen Stub, falls das Gateway nicht konfiguriert ist).", "permissions": [ "addons/marketing-ads/creatives" ], "endpoint": "/api/v1/addons/marketing-ads/creatives", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Per-User Marketing: Ad-Kampagnen (Google/Meta) mit Budget & ROAS, Affiliate-Tracking mit Klick-/Conversion-Zählern und KI-Creative-Prompts. Plattform-Spend/Revenue fließen über einen injizierbaren, per-User BYOK Fetch-Seam (nie hartcodiert); KI-Creatives hinter einem LLM-Gateway-Seam mit graceful Degradation. Lokale SQLite ist die Quelle der Wahrheit (ADR-054).
\nmarketing-ads/addons/marketing-adsKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials. Die
Google/Meta-Plattform-Integration (Spend/Revenue) ist OPTIONAL und per-User
BYOK (Bring-Your-Own-Key): Tokens liegen im Nutzer-Secret-Store und fließen über
den injizierbaren Fetch-Seam (src/lib/marketing-ads-fetch.ts). Bis eine echte
Plattform-Anbindung konfiguriert ist, läuft das Addon auf lokalen Zahlen
(graceful Degradation) — ROAS bleibt deterministisch offline. Die KI-Creative-
Generierung (src/lib/marketing-ads-creative.ts) verhält sich analog: fehlt das
LLM-Gateway, wird ein deterministischer Stub gespeichert.
| Methode(n) | Pfad |
| --- | --- |
| GET, POST | /api/v1/addons/marketing-ads/campaigns |
| PATCH, DELETE | /api/v1/addons/marketing-ads/campaigns/:id |
| GET, POST | /api/v1/addons/marketing-ads/affiliates |
| DELETE | /api/v1/addons/marketing-ads/affiliates/:id |
| POST | /api/v1/addons/marketing-ads/affiliates/:id/click |
| POST | /api/v1/addons/marketing-ads/affiliates/:id/convert |
| GET, POST | /api/v1/addons/marketing-ads/creatives |
| DELETE | /api/v1/addons/marketing-ads/creatives/:id |
| GET | /api/v1/addons/marketing-ads/stats |
Alle Routen sind userRoute + auth.id-scoped (ADR-054). Eine fremde ID ergibt
404 ohne Existenz-Leak.
- Per-User Store (src/lib/marketing-ads-store.ts): scopedStore(userId) +
registerScopedTable für marketing_ads_campaigns, marketing_ads_affiliates,
marketing_ads_creatives. ROAS = revenue / spend (0 bei Spend 0, nie Infinity).
- Affiliate-Resolver (src/lib/affiliate-link.ts): reine URL-Builder +
Resolver für /go/<code> → Ziel-URL.
- Fetch-Seam (src/lib/marketing-ads-fetch.ts): injizierbarer Google/Meta-
Adapter, BYOK-Tokens per User, graceful Degradation.
- Creative-Seam (src/lib/marketing-ads-creative.ts): injizierbares LLM-
Gateway, deterministischer Stub-Fallback.
An in-instance marketplace — one browsable catalog to discover, install, and publish agents (as
shared templates) and addons inside this Aiopta instance.
It is a thin curation layer over primitives that already exist and re-implements nothing
(ADR-026):
- Agent listings ARE shared agent_templates (Phase A / ADR-021). Install = instantiate the template
for the caller (a new agent with its own key, no secrets copied). Publish = share an agent you own.
- Addon listings are installable addons from the registry (Phase K / ADR-022). Install = enable the
available addon. A ZIP upload is a separate flow (POST /api/v1/addons/install).
- Listing = `{ id, kind:'agent'|'addon', refId, title, description, category, authorUserId,
visibility:'shared', installs, featured, installed, pricing, purchased, createdAt, source }`.
- refId is an agent_templates.id (agent) or an addon id (addon). id is synthetic
(agent:<id> / addon:<id>), and a curated mkt-<uuid> id also resolves.
- installed is computed live per caller (own shared template / enabled addon).
- pricing = `{ pricingModel:'free'|'one_time'|'subscription'|'both', priceMinor, subscriptionPriceMinor,
subscriptionInterval, currency } (money in **integer minor units**; free` by default — no regression).
- purchased = whether the caller holds a completed entitlement (buyer-scoped; always false for free).
- The addon owns ONE thin table marketplace_listings (curation metadata + install counter +
monetization columns, UNIQUE(kind, ref_id)) and a per-buyer marketplace_purchases ledger
(user_id NOT NULL, UNIQUE(user_id, listing_id)). It never copies the template payload or addon code —
those stay in their Phase-A / Phase-K homes and are read live by src/lib/catalog.ts.
- A listing can be paid: a one-time and/or subscription price + currency (monetization.ts,
pure). Free stays the default. Money mirrors the payments addon convention (minor units + ISO-4217).
- A configurable platform revenue-share % (instance-wide admin setting, Aiopta addon-config) splits each
paid transaction into a platform cut + seller payout (computeRevenueSplit, rounding-safe: cut + payout
== gross exactly). The split is recorded per transaction on the purchase row.
- A purchase reuses the payments addon read-only (provider registry + payment-link store) — no
Stripe/PayPal reimplemented. Owner creds are owner-secret (Block H): when payments is unconfigured
the paid flow is gracefully inactive (409 "payments not configured"), free listings + browsing
always work. On success the buyer gets a (pending) entitlement; a paid listing must be purchased before
it can be installed (402 otherwise).
- Policy: publishing (free or paid) uses the existing agent.create gate; editing a listing's price is
owner-scoped (seller or admin); changing the revenue-share % is mc.manage-admin-gated.
listMarketplace(user, query) merges listVisibleTemplates(user) (filtered to visibility==='shared')
with readInstalledAddonCatalog() (excluding the marketplace itself), applies q/category/kind
filters and sort (featured|installs|recent|title), and lets curated rows win over derived rows.
- Visibility-aware: only shared agent-templates are surfaced. **Another user's PRIVATE template is
never exposed** — not in browse, and not by a guessed agent:<id> (detail/install resolve through the
same function → 404).
- No secrets: publish reuses the Phase-A allow-list projection (buildTemplateFromAgent); install
mints a new own key via the Phase-A instantiate route.
- No external calls: install dispatches to the existing primitive over the same-origin Aiopta API
(assertSameOrigin); there is no container and no outbound request (ADR-009).
- RBAC: browsing is for any authed user; publishing a shared listing is owner/admin-gated (the
same agent.create capability Phase-A uses for instance-wide sharing). Editing a listing's price is
owner-scoped; the revenue-share % is mc.manage-admin-gated.
- Isolation: catalog reads are instance-wide by design (public catalog, not a leak); **listing
writes (incl. pricing) are owner-scoped** (seller user_id stamped from auth.id);
purchases/entitlements are buyer-scoped (WHERE user_id). All new raw-getDb access lives in the
already-allowlisted src/lib/store.ts; no allowlist addition was needed.
Dual-registered in addon.json + src/manifest.ts:
GET /api/v1/addons/marketplace/statusGET /api/v1/addons/marketplace/listings?kind=&category=&q=&sort=GET /api/v1/addons/marketplace/listings/[id]POST /api/v1/addons/marketplace/listings/[id]/installPOST /api/v1/addons/marketplace/listings/[id]/purchase — buy a paid listing (#122)PUT /api/v1/addons/marketplace/listings/[id]/pricing — set a listing's price (owner/admin, #122)GET + PUT /api/v1/addons/marketplace/revenue-share — read / set the platform % (PUT admin-only, #122)POST /api/v1/addons/marketplace/publishGET /api/v1/addons/marketplace/widgetSee SKILL.md for the agent-facing endpoint cheat-sheet, and docs/architecture/ADR-026-marketplace.md
(incl. the monetization addendum) for the full decision. Paid listings are now supported (OPEN-DECISIONS
#33 resolved); cross-instance/remote-registry marketplace remains parked (OPEN-DECISIONS #32).
Manage marketplace accounts, create listing drafts, publish to supported portals, and track publish jobs from inside Aiopta.
\nmarketplace-automation/addons/marketplace-automationKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| GET, POST, DELETE | /api/v1/addons/marketplace-automation/accounts |
| GET, PUT | /api/v1/addons/marketplace-automation/accounts/[id] |
| GET | /api/v1/addons/marketplace-automation/jobs |
| GET, POST | /api/v1/addons/marketplace-automation/listings |
| GET, PUT | /api/v1/addons/marketplace-automation/listings/[id] |
| POST | /api/v1/addons/marketplace-automation/listings/[id]/publish |
| GET | /api/v1/addons/marketplace-automation/status |
", "byteSize": 1197 } } }, { "id": "mcp", "uuid": "c0f71398-0eeb-4cf5-b840-a6b83c5879ac", "name": "MCP Servers", "version": "1.3.3", "description": "Model Context Protocol server management, runtime installation, tool discovery, agent tool execution, and per-user least-privilege tool policies (addons#178).", "author": "Aiopta", "icon": "🧩", "capabilities": [ "mcp", "tools", "servers", "agent-tools" ], "tags": [], "download": "/artifacts/mcp-1.3.3.zip", "sha256": "61689e3aa3408ac8d7c3d494887d4da0e7d6268b22596937c8e626997ec1f60d", "size": 408987, "page": { "id": "mcp", "path": "/addons/mcp", "name": "MCP Servers", "icon": "🔌", "section": "Admin", "component": "@addons/mcp/src/components/MCPPage" }, "deprecated": false, "endpoints": [ "/api/v1/addons/mcp/agent", "/api/v1/addons/mcp/deploy", "/api/v1/addons/mcp/servers", "/api/v1/addons/mcp/servers/{id}", "/api/v1/addons/mcp/servers/{id}/discover", "/api/v1/addons/mcp/servers/{id}/test-auth", "/api/v1/addons/mcp/servers/{id}/tool-policy", "/api/v1/addons/mcp/servers/{id}/tools", "/api/v1/addons/mcp/tools" ], "skills": [], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Model Context Protocol server management, runtime installation, tool discovery, and agent tool execution.
\nmcp/mcpOptionale BYOK-Credentials pro MCP-Server (auth.token). Diese sind pro Benutzer privat.
type: "http" bedeutet standardkonformes MCP Streamable HTTP (offizielles@modelcontextprotocol/sdk). type: "sse" ist Legacy-SSE und nutztSSEClientTransport aus demselben SDK.
source.url ist der vollständige MCP-Endpunkt — inklusive einer etwaigen
Secret-Path-Komponente wie http://HA-IP:9583/private_<secret>. Es wird **kein
Pfadsegment** angehängt (/health, /tools, /mcp o.ä.). Der Endpunkt wird
nur getrimmt und als URL validiert.
Unterstützte Auth-Modi:
\n| auth.type | Verhalten |
|---|---|
| none | Kein Authorization-Header. |
| token (statischer Bearer) | requestInit.headers.Authorization: Bearer <token> — Token passiert ausschließlich diesen Pfad. |
| oauth (Authorization-Code-Flow) | Nicht unterstützt — saubere not supported-Fehlermeldung ohne Fallback. |
Health = erfolgreicher MCP-initialize-Handshake am konfigurierten Endpunkt
(optional gefolgt von tools/list). Es gibt keinen proprietären /health
Endpunkt mehr.
Sicherheits-Disziplin:
\n- Das Bearer-Token und der Secret-Path-Anteil der URL werden nie geloggt,
nie in Fehlermeldungen gespiegelt und nie über die API zurückgegeben.
- Per userId::serverId existiert genau ein verbundener SDK-Client +
Transport; zwei Nutzer mit demselben Server-Slug bleiben vollständig
isoliert (ADR-054).
MCP-Server sind pro Benutzer isoliert (BYOK). Jeder registrierte Server — inklusive seinesauth.token — gehört ausschließlich dem anlegenden Benutzer und liegt in der user-gescopten
Tabelle mcp_servers (über scopedStore(auth.id)), nicht mehr in einer geteilten Datei.
- Reads/Updates/Deletes sehen nur die eigenen Server; eine fremde Server-ID liefert 404.
- Der rohe auth.token wird über die API nie zurückgegeben (maskiert als ••••••) — auch nicht
an den Besitzer.
- Die Agent-Tool-Ausführung (POST /agent) löst nur die Server des Agent-Besitzers auf; ein
fremder Agent kann die BYOK-Server eines Benutzers nicht betreiben.
- Der mitgelieferte config/mcp-servers.json ist nur noch ein read-only Instanz-Katalog von
Default-Server-Definitionen (ohne Secrets), aus dem die privaten Zeilen eines Benutzers beim
ersten Zugriff geseedet werden (alle deaktiviert, ohne Token).
homeassistant-ai/ha-mcp veröffentlicht 84 Werkzeuge; ohne Profile könnte ein Agent nach Eingabe
einer Secret-URL unmittelbar den gesamten schreibenden und teils destruktiven HA-Katalog
bedienen. Die MCP-Integration filtert daher jede Tool-Sicht und jeden tools/call durch die
Least-Privilege-Policy des Server-Owners, bevor der Aufruf an den MCP-Transport geht
(zweistufig: Discovery-Filter + Execution-Gate).
Pro mcp_servers-Zeile existiert eine Policy in der Spalte tool_policy_json
(Default: custom + leere Listen = Default-Deny). Optional überschreibt eine zweite,
per-User Override in mcp_tool_policies (scopedStore(userId)) die Server-Konfig — der
Override ersetzt die Server-Policy (kein Merge, ADR-054).
| Feld | Mögliche Werte | Bedeutung |
|---|---|---|
| mode | custom \\| read-only \\| write \\| full | Steuert die annotations-getriebene Auswahl. custom = nur Listen zählen. |
| allowDestructive | boolean | Nur unter mode: "full" wirksam. Öffnet destructive Tools. |
| allowedTools | string[] | Optionale Allowlist (zusätzlich zur Mode-Grenze; kann sie nicht erweitern). |
| deniedTools | string[] | Denylist — gewinnt immer gegen die Allowlist. |
| Mode | Sichtbar sind … | destructiveHint: true … |
|---|---|---|
| custom (Default) | nur allowedTools (ohne deniedTools) | wie der Mode bzw. die Liste es hergibt |
| read-only | Tools mit annotations.readOnlyHint === true | blockiert |
| write | Read-only + nicht-destruktive Write-Tools | blockiert |
| full | alle nicht-destruktiven Tools | blockiert — allowDestructive: true hebt es auf |
| _kein Mode / fehlende Annotation_ | _nichts_ (Default-Deny) | blockiert |
- Default-Deny: leere / fehlende Policy → kein Tool ist sichtbar. Es gibt keinen stillen
Default-Allow.
- Fehlende oder widersprüchliche Annotationen bleiben in jedem annotation-getriebenen Mode
unsichtbar — ein Tool ohne annotations ist im read-only-, write- und full-Mode blockiert.
- Cache-Stale-State: ein bereits entdeckter Tool-Aufruf wird nach Policy-Verschärfung
sofort blockiert — der Execution-Gate liest die Policy unmittelbar vor tools/call neu.
- Direkter Execute-Request auf ein blockiertes Tool ergibt 403 mit MCP_TOOL_DENIED,
ohne Argumente, Token oder Secret-Path-URL in der Fehlermeldung.
- Per-User-Isolation: mcp_tool_policies ist UNIQUE(user_id, server_id) — zwei Nutzer
mit demselben Slug haben distinkte Overrides. Eine Policy-Änderung von A berührt B nie.
- Legacy-Fallback (bestehende Server ohne tool_policy_json): die Spalte wird mit der
"legacy full" Policy (mode: "full", allowDestructive: false) back-gefüllt. Das
HA-MCP-Onboarding MUSS dagegen explizit read-only schreiben.
- Race-Safety: das Lesen der effektiven Policy läuft in einer Transaktion; ein gleichzeitiger
PATCH + callTool reißt den Zustand nicht.
- ha_config_set_yaml, ha_write_file, ha_delete_file sind immer Default-Deny.
Sie tauchen ohne explizite Allowlist in keiner Mode-Sicht auf und werden am Gate
durch McpToolDeniedError (kein Token, keine Argumente, kein Secret-Path) abgewiesen.
- full + allowDestructive: true erfordert in der UI eine zweite ausdrückliche Bestätigung
(Tippen der Server-ID); die UI schaltet allowDestructive niemals stillschweigend frei.
- Der Status zeigt, ob ha_manage_backup bzw. die Upstream-Safety-Tools entdeckt wurden.
| Methode | Pfad | Effekt |
|---|---|---|
| GET | /api/v1/addons/mcp/servers/{id}/tool-policy | Effective Policy + source (user-override \\| server-config \\| default) |
| PUT | /api/v1/addons/mcp/servers/{id}/tool-policy | Installiert / ersetzt den per-User Override (validiert). |
| DELETE | /api/v1/addons/mcp/servers/{id}/tool-policy | Entfernt den Override; Server-Konfig greift wieder. |
Fremde Server-IDs liefern 404 (kein Existenz-Leak). PUT validiert mode, allowDestructive
und die Listen — ein leerer Body ist 400, niemals Default-Deny-Fallback.
| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/mcp/agent |
| POST | /api/v1/addons/mcp/deploy |
| GET, POST, PATCH | /api/v1/addons/mcp/servers |
| GET, DELETE, PATCH | /api/v1/addons/mcp/servers/[id] |
| GET, POST | /api/v1/addons/mcp/servers/[id]/discover |
| POST | /api/v1/addons/mcp/servers/[id]/test-auth |
| GET, PUT, DELETE | /api/v1/addons/mcp/servers/[id]/tool-policy |
| GET | /api/v1/addons/mcp/servers/[id]/tools |
| GET, POST | /api/v1/addons/mcp/tools |
- Der MCP-Tool-Schema-Cache (config/mcp-tools-registry.json) und der npm-Runtime-Installer sind
instanzweit (geteilt) — sie enthalten keine Secrets; der Per-User-Zugriff wird in den Routen
erzwungen (jeder Read/Sync ist auf die eigenen Server beschränkt).
- OAuth Authorization-Code-Flow ist nicht Bestandteil dieses Addons — ein entsprechender Server
erhält eine MCP_UNSUPPORTED_AUTH-Fehlermeldung ohne Fallback.
- Das config/mcp-servers.json ist read-only; eine Änderung am dort hinterlegten
toolPolicy wird beim nächsten Seeden in die per-User-Zeile übernommen. Das HA-MCP-
Onboarding wird in einem separaten Issue ausgeliefert und schreibt read-only explizit.
Home media server management — Plex, Jellyfin, Sonarr, Radarr, qBittorrent, and more. Monitor what's playing, manage libraries, request new content, and control downloads.
\nmedia/addons/mediaDieses Addon benötigt folgende Secrets/Provider-Konfiguration (Settings → Credentials bzw. Provider-Store, nie in addon.json):
\nMEDIA_JELLYFIN_KEYMEDIA_LIDARR_KEYMEDIA_OVERSEERR_KEYMEDIA_PLEX_TOKENMEDIA_PROWLARR_KEYMEDIA_QBIT_PASSWORDMEDIA_RADARR_KEYMEDIA_READARR_KEYMEDIA_SABNZBD_KEYMEDIA_SONARR_KEYMEDIA_TAUTULLI_KEYDie ENV-Werte dienen nur als gemeinsame Fallback-Baseline. Die eigentliche Konfiguration (Service-URLs + BYOK-Secrets) wird pro Nutzer über GET/POST /config gepflegt.
Die Media-Konfiguration ist pro authentifiziertem Aiopta-Nutzer isoliert: Sie liegt in einer
user-gescopten Tabelle (media_config, UNIQUE(user_id)) über scopedStore(auth.id), und jedeMediaRegistry (samt der daraus gebauten Service-Clients) wird pro Nutzer aufgebaut — kein
prozessweiter Singleton mehr. Konsequenzen:
- GET /config maskiert apiKey/token/password standardmäßig. GET /config?edit=true liefert
die Klartext-Secrets ausschließlich für die eigene Konfiguration des Aufrufers — niemals die
eines anderen Nutzers.
- POST /config schreibt nur die eigene Zeile; ein Nutzer kann die Credentials eines anderen weder
lesen noch überschreiben.
- Der frühere globale data/media-config.json-Blob wird beim ersten Zugriff einmalig in den
Namespace des Seeding-Admins migriert und anschließend gelöscht.
| Methode(n) | Pfad |
|---|---|
| POST | /api/v1/addons/media/auto-confirm-import |
| GET, POST, DELETE | /api/v1/addons/media/blacklist |
| GET, POST | /api/v1/addons/media/config |
| PUT | /api/v1/addons/media/config/auto-request |
| GET | /api/v1/addons/media/diagnose |
| GET, DELETE | /api/v1/addons/media/download-queue |
| POST | /api/v1/addons/media/download-queue/bulk-delete |
| POST | /api/v1/addons/media/fix |
| GET | /api/v1/addons/media/health |
| GET | /api/v1/addons/media/history |
| GET | /api/v1/addons/media/libraries |
| POST | /api/v1/addons/media/libraries/bulk-delete |
| DELETE | /api/v1/addons/media/libraries/items |
| POST | /api/v1/addons/media/libraries/refresh |
| POST | /api/v1/addons/media/libraries/scan |
| PUT | /api/v1/addons/media/monitor |
| GET | /api/v1/addons/media/popular |
| GET | /api/v1/addons/media/propose-import |
| GET | /api/v1/addons/media/releases |
| POST | /api/v1/addons/media/releases/add-language-priority |
| GET | /api/v1/addons/media/releases/detail |
| POST | /api/v1/addons/media/releases/grab |
| GET, POST, DELETE | /api/v1/addons/media/releases/language-profile |
| POST | /api/v1/addons/media/releases/search |
| GET, POST | /api/v1/addons/media/releases/search-custom |
| POST | /api/v1/addons/media/releases/upgrade-language |
| POST | /api/v1/addons/media/request |
| GET, PUT, DELETE | /api/v1/addons/media/requests |
| POST | /api/v1/addons/media/retry-import |
| GET | /api/v1/addons/media/search |
| GET | /api/v1/addons/media/search/advanced |
| GET | /api/v1/addons/media/sessions |
| POST | /api/v1/addons/media/sessions/terminate |
| GET | /api/v1/addons/media/stats/downloads |
| GET | /api/v1/addons/media/stats/requests-stats |
| GET | /api/v1/addons/media/stats/storage |
| GET | /api/v1/addons/media/stats/watch |
| GET | /api/v1/addons/media/status |
| GET | /api/v1/addons/media/trending |
| GET | /api/v1/addons/media/upcoming |
| POST, DELETE | /api/v1/addons/media/users/ban |
", "byteSize": 4122 } } }, { "id": "membership", "uuid": "56d99555-98da-45fe-be6c-7040dd69466c", "name": "Membership (Mitglieder/Abos/Paywall/Kurse/E-Books)", "version": "1.0.3", "description": "Per-User Mitgliedschaften: Mitglieder, Abo-Stufen mit Entitlement-Bündeln, Subscriptions (Paywall-Autorität), Kurse und E-Books. Integriert lesend mit dem payments-Addon (ein Abo darf die billing-Subscription referenzieren), ohne payments zu verändern. Lokale SQLite ist die Quelle der Wahrheit (ADR-054).", "author": "Aiopta", "icon": "🎟️", "capabilities": [ "membership", "members", "plans", "subscriptions", "paywall", "entitlements", "courses", "ebooks" ], "tags": [], "download": "/artifacts/membership-1.0.3.zip", "sha256": "e2ccced777fab1bfa17ce2bee47263480024ed3d72b77e35ca30be051ec81424", "size": 130887, "page": { "id": "membership-page", "path": "/addons/membership", "name": "Membership", "icon": "🎟️", "section": "Money", "component": "@addons/membership/src/components/MembershipPage" }, "deprecated": false, "endpoints": [ "/api/v1/addons/membership/members", "/api/v1/addons/membership/members/:id", "/api/v1/addons/membership/plans", "/api/v1/addons/membership/plans/:id", "/api/v1/addons/membership/subscriptions", "/api/v1/addons/membership/subscriptions/:id", "/api/v1/addons/membership/courses", "/api/v1/addons/membership/courses/:id", "/api/v1/addons/membership/ebooks", "/api/v1/addons/membership/ebooks/:id", "/api/v1/addons/membership/entitlements" ], "skills": [ { "name": "membership-read", "displayName": "Membership: Mitglieder, Abos & Inhalte lesen", "description": "Listet Mitglieder, Abo-Stufen, Subscriptions, Kurse und E-Books für den Nutzer und prüft den Entitlement-/Paywall-Status. Reiner Lesezugriff — legt nichts an.", "permissions": [ "addons/membership/members", "addons/membership/plans", "addons/membership/subscriptions", "addons/membership/courses", "addons/membership/ebooks", "addons/membership/entitlements" ], "endpoint": "/api/v1/addons/membership/entitlements", "scripts": [] }, { "name": "membership-manage", "displayName": "Membership: Mitglieder & Abos verwalten", "description": "Legt Mitglieder, Abo-Stufen und Subscriptions an oder entfernt diese (per-User gebucht). Setzt den Subscription-Status, auf dem die Paywall entscheidet.", "permissions": [ "addons/membership/members", "addons/membership/plans", "addons/membership/subscriptions" ], "endpoint": "/api/v1/addons/membership/subscriptions", "scripts": [] }, { "name": "membership-content", "displayName": "Membership: Kurse & E-Books verwalten", "description": "Legt Kurse und E-Books im geschützten Inhaltskatalog des Nutzers an oder entfernt diese (mit erforderlichem Entitlement).", "permissions": [ "addons/membership/courses", "addons/membership/ebooks" ], "endpoint": "/api/v1/addons/membership/courses", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Per-User Mitgliedschaften: Mitglieder, Abo-Stufen mit Entitlement-Bündeln, Subscriptions (Paywall-Autorität), Kurse und E-Books. Integriert lesend mit dem payments-Addon (ein Abo darf die billing-Subscription referenzieren, ohne payments zu verändern). Lokale SQLite ist die Quelle der Wahrheit (ADR-054).
\nmembership/addons/membershipKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials. Die
payments-Integration ist optional und degradiert graceful, falls payments nicht
installiert/verfügbar ist.
| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/membership/members |
| DELETE | /api/v1/addons/membership/members/[id] |
| GET, POST | /api/v1/addons/membership/plans |
| DELETE | /api/v1/addons/membership/plans/[id] |
| GET, POST | /api/v1/addons/membership/subscriptions |
| PATCH, DELETE | /api/v1/addons/membership/subscriptions/[id] |
| GET, POST | /api/v1/addons/membership/courses |
| DELETE | /api/v1/addons/membership/courses/[id] |
| GET, POST | /api/v1/addons/membership/ebooks |
| DELETE | /api/v1/addons/membership/ebooks/[id] |
| GET | /api/v1/addons/membership/entitlements |
", "byteSize": 1730 } } }, { "id": "memories", "uuid": "477f94c5-8620-46fc-be34-c9ce4de3d8ba", "name": "Memories", "version": "1.5.2", "description": "Long-term memories, memory search, memory group sharing, and a per-user knowledge-map graph.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "memories", "memory-groups", "search", "sharing", "knowledge-map", "memory-loop" ], "tags": [], "download": "/artifacts/memories-1.5.2.zip", "sha256": "df694028a0db5bb71abf8e6b0df635143d5a836ba453e16d47b9b8ed05fcbcb0", "size": 380252, "page": [ { "id": "memories", "path": "/addons/memories", "name": "Memories", "icon": "🧠", "section": "Data", "component": "@addons/memories/src/components/memories/MemoryList" }, { "id": "memories-graph", "path": "/addons/memories/graph", "name": "Knowledge Map", "icon": "🕸️", "section": "Data", "component": "@addons/memories/src/components/memories/MemoryGraph" }, { "id": "memories-loop", "path": "/addons/memories/agent-loop", "name": "Memory-Loop", "icon": "♻️", "section": "Data", "component": "@addons/memories/src/components/memories/MemoryLoopSettings" } ], "deprecated": false, "endpoints": [ "/api/v1/addons/memories", "/api/v1/addons/memories/{id}", "/api/v1/addons/memories/search", "/api/v1/addons/memories/graph", "/api/v1/addons/memories/memory-groups", "/api/v1/addons/memories/memory-groups/{id}", "/api/v1/addons/memories/memory-groups/{id}/members", "/api/v1/addons/memories/memory-groups/{id}/memories", "/api/v1/addons/memories/memory-groups/share", "/api/v1/addons/memories/memory-groups/visible", "/api/v1/addons/memories/agent-loop/settings", "/api/v1/addons/memories/agent-loop/sync" ], "skills": [], "mcpServers": [ { "id": "memories-tools", "displayName": "Memories tools", "description": "Read-only knowledge-map math for agents: extract [[name]] cross-links and assemble the memory/group knowledge graph (nodes, dedup edges, membership) — the same pure builder the memories knowledge-map uses (issue #429, epic #399). Reads nothing external.", "transport": "stdio", "runtime": "node", "entry": "memories-tools/server.mjs", "permissions": [ "addons/memories/read" ], "toolPolicy": { "mode": "read-only", "allowDestructive": false }, "configRefs": [], "credentialRefs": [], "archiveEntry": "memories/mcp/servers/memories-tools/server.mjs", "sha256": "a2eaa5b2d66fba6274d77e1fdcb8cf3167f7750308c2ce6a0d508d8540812c9b", "size": 16130, "descriptorVersion": 1 } ], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Long-term memories, memory search, memory group sharing, and a per-user knowledge-map graph.
\nmemories/memories (Liste), /memories/graph (Wissenskarte), /memories/agent-loop (Memory-Loop-Einstellungen)Keine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/memories |
| GET, PUT, DELETE | /api/v1/addons/memories/[id] |
| GET, POST | /api/v1/addons/memories/memory-groups |
| GET, PUT, DELETE | /api/v1/addons/memories/memory-groups/[id] |
| GET, POST, DELETE | /api/v1/addons/memories/memory-groups/[id]/members |
| GET, POST, DELETE | /api/v1/addons/memories/memory-groups/[id]/memories |
| POST | /api/v1/addons/memories/memory-groups/share |
| GET | /api/v1/addons/memories/memory-groups/visible |
| GET | /api/v1/addons/memories/search |
| GET | /api/v1/addons/memories/graph |
| GET, POST | /api/v1/addons/memories/agent-loop/settings |
| POST | /api/v1/addons/memories/agent-loop/sync |
Die UI-Seite /memories/graph rendert die eigenen Erinnerungen + Memory-Groups als interaktiven
Graphen (SVG, keine zusätzliche Abhängigkeit — force-directed Layout):
- Knoten = Erinnerungen (violett, Größe ∝ importance) und Memory-Groups (bernstein).
- Kanten = [[name]]-Querverweise zwischen Erinnerungen (durchgezogen, titel-aufgelöst,
case-insensitiv, ungerichtet entdoppelt) sowie Memory↔Group-Zugehörigkeit aus
memory_group_memories (gestrichelt).
- Interaktion = Zoom (Scrollen), Pan (Hintergrund ziehen), Klick auf einen Knoten öffnet die
Erinnerung (Detail-Panel via scoped [id]-Route) bzw. fokussiert auf eine Gruppe; Filter nach Gruppe.
Die Graph-Daten kommen ausschließlich aus den bereits pro-Nutzer-isolierten Stores
(listMemories/listGroups/getGroupMemories, alle auf auth.id gescoped) — GET …/graph istuserRoute-gewrappt. Ein [[name]] kann daher nur auf eine eigene Erinnerung auflösen, nie auf die
eines anderen Tenants.
Agenten schreiben ihre Outputs/Insights automatisch als Erinnerungen zurück (Contributor-Pattern)
— opt-in, standardmäßig AUS, mit optionalem Obsidian-Export. Die UI-Seite /memories/agent-loop
steuert die per-Nutzer-Einstellung.
- Event-getrieben, zweiter Subscriber: Das Addon abonniert das kanonische Event
agent.output.produced (ADR-053, eingeführt in #148) ein zweites Mal, unabhängig vom
artefakt-workspace — derselbe Event erzeugt sowohl ein Artefakt (#148) als auch eine Erinnerung,
ohne Kopplung. Abo lazy+idempotent im install() (globalThis-Singleton, kein Boot-Hook).
- Ownership (ADR-054): Der Besitzer kommt IMMER aus dem Event-Payload (userId/user_id/ownerId),
NIE aus einem Client-Wert; ein Event ohne erkennbaren Nutzer wird übersprungen (geloggt), nicht
geraten. Der Write läuft über den per-Nutzer-createMemory-Store ⇒ user_id server-seitig gestempelt.
- Contributor-Provenance: Jede agent-erzeugte Erinnerung ist von menschlichen unterscheidbar —
Kategorie agent-contributed, Tags agent-contributed + agent:<id> + event:<id>, plus
Provenienz-Footer im Body (Quell-Agent + Source-Event).
- Opt-in (default OFF): per-Nutzer-Einstellung in addon_settings (addon_id='memories-loop',
über scopedStore); ohne explizites enabled: true wird nichts geschrieben. Optionaler
per-Agent-Allowlist (leer = alle Agenten).
- Optionaler Obsidian-Sync (default OFF): exportiert jede Erinnerung als eine Markdown-Datei
(Frontmatter + Body + native [[links]]) unter resolveUserPath(user,'memories','obsidian',...)
⇒ <DATA_DIR>/addons/memories/<userId>/obsidian (containment-checked; ein ../-Escape wird mit
403 abgewiesen). Manueller Re-Export via POST …/agent-loop/sync (nur wenn aktiviert).
Alle Daten sind pro Nutzer isoliert (default-deny über die scopedStore-Foundation):
- agent_memories, memory_groups, memory_group_members und memory_group_memories tragen je eine
user_id-Spalte (NOT NULL). Der Server stempelt user_id = auth.id bei jedem Insert — ein
client-gelieferter agent_id/created_by/shared_by ist nur ein gruppierender Schlüssel, nie die
Sicherheitsgrenze.
- Jeder Read/Update/Delete ist auf den aufrufenden Nutzer gescoped. Eine fremde oder unbekannte {id}
liefert 404 (nie die Zeile eines anderen Nutzers, nie 403). Die [id]-Routen laufen über
userRoute/ownedResourceRoute — eine unauthentifizierte Anfrage wird mit 401 abgewiesen (der
frühere no-auth-IDOR ist geschlossen).
- Teilen funktioniert nur innerhalb des eigenen Besitzes: man kann ausschließlich eine eigene Memory
in eine eigene Gruppe teilen.
Erzeugt eine Formdatei zu einem Modell, indem es die Meshcast-Weboberfläche
fernsteuert — und prüft das Ergebnis, bevor es als Form gilt.
Mehr macht dieses Addon nicht. Kein Preis, kein Schnitt, kein Auftrag: die Kette
(Analyse → Preis → Schnitt → Druck) liegt im Slice-Dienst und im Addonlayery-druckzentrale.
\nTicket: addons#1259
Nachbarvorhaben: addons#1243 — die eigene Formgeometrie im Slice-Dienst
Der Betreiber hat am 11.08.2026 entschieden, beides zu haben:
\n* Die eigene Geometrie (#1244–#1249) läuft ohne Handgriff durch die Kette.
Sie ist der Regelweg.
* Meshcast ist der Sonderfall und der Vergleichsmaßstab. Es ist ein fremdes
Werkzeug, das ein Mensch im Browser bedient; es kann nicht in einer Strecke
stehen, die vom Bestelleingang bis zum Angebot ohne Zutun läuft. Was es kann,
ist die Messlatte, an der sich die eigene Form messen lassen muss.
Von vier vorgelegten Wegen hat der Betreiber „Browser fernsteuern" gewählt,
ausdrücklich im Wissen darum, dass das bei jeder Änderung der fremden Seite
bricht. Auflage: der Bruch muss laut sein. Wie das gebaut ist, steht unter
Wenn es bricht.
Alles Folgende ist an der Seite selbst nachgemessen, nicht aus einer
Beschreibung übernommen.
Eingang STL, OBJ oder 3MF (bestätigt über die dynamisch geladenen BündelSTLLoader, OBJLoader, 3MFLoader) oder eine mitgelieferte Grundform;
Ausgang „watertight, print-ready STL" bzw. 3MF. Das Netz muss **wasserdicht
(manifold)** sein, sonst kann der Generator nicht sauber abziehen.
Die Datenschutzerklärung der Seite sagt es selbst, wörtlich:
\n\n„Most generators run entirely in your browser via WebAssembly, so your file
never leaves your device at all."
\n„A few of the more advanced mold generators need heavier computation and send
your model's geometry to our generation server purely to build the mold."
Welche „few" das sind, sagt die Seite nicht. Für einen Druckdienst, der
fremde Kundenmodelle verarbeitet, ist das keine Fußnote, sondern eine
Datenschutzfrage. Deshalb wurde es gemessen: für jede der 28 Werkzeugseiten
wurde der Bündelgraph geladen und geprüft, ob er den Aufruf run-pipeline
enthält — den einzigen Weg, auf dem die Oberfläche Geometrie an den Rechenserver
gibt.
Neun Generatoren rechnen serverseitig (das Kundenmodell verlässt das Gerät):
\n| Pfad | Generator | Pipeline |
| --- | --- | --- |
| /adaptive-silicone | Adaptive Silikonform | adaptive-silicone |
| /candle-mold | Kerzenform (Zweiteilform) | boxmold |
| /photo-candle-mold | Fotokerzenform | boxmold |
| /silicone-mold | Wiederverwendbare Silikonform | — |
| /plaster-mold | Gipsform für Schlickerguss | — |
| /press-mold | Press-Form für Ton und Seife | bathbomb |
| /vase-mold | Vasen- und Pflanzgefäßform | — |
| /texture-roller | Texturrolle | texture-roller-handle |
| /packaging-insert | Verpackungseinlage | shipping-cradle |
Alle übrigen rechnen im Browser — darunter ausdrücklich die Hauptform/mold (Zweiteilform mit Trennebene, Passstiften und Angusskanal): ihr Bündelmain-*.js enthält kein run-pipeline. Ebenso /cutter, /lithophane,/nameplate, /embosser, /keychain, /golf-ball-stencil, /planter,/pottery-mold, /carbon-fiber-mold, /ice-cube-tray-mold,/print-splitter, /svg-to-stl.
Der Katalog steht in generatoren.json und ist die eine Quelle für die
Addon-Laufzeit und den MCP-Server. Die Oberfläche zeigt den Rechenort vor
dem Lauf; ein Generator außerhalb des Katalogs gilt vorsorglich als
serverseitig und lässt sich gar nicht erst starten.
Gemessen auf der Preisseite, wörtlich:
\n| Stufe | Preis | Umfang |
| --- | --- | --- |
| Free | 0 | „5 free STL downloads a week, across every tool, with a free account" + „3 bonus downloads" für die Anmeldung · „Personal use only - not for resale" · „Small 'Meshcast' engraving on each STL" |
| Pro | „$20 / mo" | „Sell everything you make as many copies as you like", unbegrenzt, eigenes Logo |
| Founder | „$349 / once" | „Everything in Pro for life" |
Ein Druckdienst ist gewerblich.
\nDie Seite bewirbt keine API. Gesucht wurde trotzdem, und gefunden:
\n| Aufruf | Befund |
| --- | --- |
| GET https://api.meshcast.app/queue-status | 200, öffentlich, JSON (max_concurrent, running, waiting_priority, waiting_normal) |
| GET https://api.meshcast.app/health | 200, öffentlich: {"ok":true,"checks":{"run_build123d_multi.py":true,"run_manifold_multi.mjs":true,"pipelines":true}} |
| POST https://api.meshcast.app/run-pipeline/<slug> | die Erzeugungsschnittstelle; Rumpf { params, upload_stl_base64 }, Kopf X-User-Plan: free\\|paid |
| GET /openapi.json, GET /docs | 404 ({"detail":"Not Found"} — FastAPI mit abgeschalteter Doku) |
Sie wäre der bequemere Weg. Zwei Gründe sprechen dagegen, und der zweite ist der
ernstere:
1. Sie ist undokumentiert und ohne Zusage. Jede Änderung bricht sie ohne
Ankündigung, und anders als bei der Oberfläche gäbe es keine Fehlerseite, an
der man es merkt.
2. Der Downloadzähler und die Lizenzstufe sitzen im Browser
(downloadGate-*.js, quotaWindow-*.js). An der API vorbei zu rechnen hieße,
die Lizenzbedingung des Anbieters zu umgehen — unabhängig davon, welche Stufe
der Betreiber gebucht hat.
Der Befund steht hier, damit ihn niemand ein zweites Mal suchen muss.
\nAlles über die Addon-Einstellungen. Kein Feld hat einen Vorgabewert.
\n| Feld | Pflicht | Bedeutung |
| --- | --- | --- |
| basisUrl | ja | Wurzel der fernzusteuernden Oberfläche, ohne Pfad |
| zeitgrenzeSekunden | ja | 10–1800; wie lange ein Schritt höchstens wartet |
| wiederholungen | ja | 0–5; Wiederholungen vor dem auslösenden Griff |
| lizenzstufe | nein | frei, pro oder founder — reine Anzeige |
| anmeldename | nein | Konto beim Anbieter (Secret) |
| anmeldewort | nein | Kennwort (Secret) |
Warum auch die Basis-URL Pflicht ist, obwohl der Wirt hier kein eigener
Dienst ist: ein vorbelegter Wirt hieße, dass eine fremde Aiopta-Installation ein
Kundenmodell an einen Dritten schickt, den ihr Betreiber nie eingetragen hat.
Wer fernsteuert, trägt ein, wen er fernsteuert. Ist das Feld leer, antwortet
jede Route mit 503 meshcast_not_configured — bevor ein Browser startet.
Ein Erfahrungswert für zeitgrenzeSekunden steht bewusst nicht imsettingsSchema (er wäre eine Vorgabe): die neun serverseitigen Generatoren
rechnen spürbar länger als die im Browser und stehen zusätzlich in einer
Warteschlange (/queue-status), die browserseitigen sind meist in Sekunden
fertig.
Dieses Addon bringt keinen eigenen Browser mit. Es hängt hart anbrowser >= 1.4.0, das Puppeteer und Chromium einmal containerweit
bereitstellt. Fehlt die Laufzeit, sagt das Addon das mit Verweis aufPOST /api/v1/addons/browser/install-runtime — es installiert nichts nach.
Der Zugang ist hinterlegbar und wird als Secret behandelt (er erscheint in
keiner Antwort; die Oberfläche zeigt nur, ob er hinterlegt ist). Die Anmeldung
selbst wird nicht automatisch durchgeklickt: sie läuft gemessen über einen
fremden Anmeldedienst (Supabase) mit Magic-Link bzw. OAuth, und so etwas blind
nachzuklicken hieße raten. Stattdessen läuft der Browser auf einem **bleibenden
Profilverzeichnis** unter DATA_DIR/meshcast/profil — einmal von Hand anmelden,
die Sitzung überlebt. Erkennt der Ablauf einen abgemeldeten Zustand, bricht er
mit 409 meshcast_not_signed_in ab, statt eine Anmeldeseite als Form abzulegen.
Betreiber, 11.08.2026:
\n\n„Free zum Ausprobieren, aber nicht bei gewerblichen Aufträgen weigern. Der
User ist verantwortlich für die Lizenz (Login muss natürlich angegeben werden
können). Ich entscheide mich später für eine Lizenz."
Also: das Addon verweigert nichts — egal welche Stufe hinterlegt ist oder ob
gar keine hinterlegt ist. Was es tut, ist den Zustand zeigen:
* die konfigurierte Stufe (und ausdrücklich „nicht hinterlegt", wenn keine da
ist — das ist nicht dasselbe wie „frei"),
* die Läufe im rollenden Sieben-Tage-Fenster,
* und den gemessenen Satz der Gegenseite wörtlich in der Oberfläche:
Personal use only - not for resale.
Der Zähler zählt nur, was dieses Addon ausgelöst hat. Was der Betreiber
daneben von Hand im Browser herunterlädt, zählt die Gegenseite mit, dieser Stand
nicht — er ist eine Untergrenze, kein Kontostand. Das steht so auch in der
Oberfläche.
Bricht Meshcast selbst wegen erschöpftem Kontingent ab, ist das ein **benannter
Fehler mit dem echten Grund** (409 meshcast_quota_exhausted, „Wochenkontingent
erschöpft"). Bei der freien Stufe tritt das nach fünf Formen ein — der Fall ist
als Normalfall behandelt, nicht als Störung.
Jeder Schritt der Fernsteuerung besteht aus drei Teilen, und der dritte ist der,
den man weglässt, wenn man es eilig hat: **die Prüfung, dass der erste getroffen
hat.** Es gibt in fernsteuerung.ts keinen Zweig, der weiterklickt, weil ein
Element nicht da war.
| Schritt | Ursache bei Fehlschlag |
| --- | --- |
| Seite öffnen | „Oberfläche nicht erreichbar" |
| Generatorauswahl | „Generatorauswahl nicht gefunden" |
| Modell hochladen | „Hochladefeld nicht gefunden" |
| Erzeugen auslösen | „Erzeugen-Schaltfläche nicht gefunden" |
| Herunterladen auslösen | „Herunterladen-Schaltfläche nicht gefunden" |
| Download abwarten | „Kein Download innerhalb der Zeitgrenze" |
Die Antwort trägt Schritt und Ursache (502 meshcast_step_failed). Genau
daran erkennt der Betreiber, ob die Gegenseite ihre Oberfläche geändert hat.
Alles, was brechen kann, liegt an einer Stelle: die Auswahlketten ingeneratoren.json. Wie brüchig das ist, zeigt die Messung selbst — die
Erzeugen-Schaltfläche heißt auf der Hauptform #generateBtn, auf der adaptiven
Silikonform #generate-btn, auf der Verpackungseinlage #sc-generate und beim
Pflanzgefäß #planter-generate-btn. Es gibt keine Systematik, nur die Messung.
Eine Wiederholung, die es bis zum auslösenden Griff schafft, verbraucht bei der
freien Stufe einen der fünf Wochendownloads — auch dann, wenn der erste Versuch
erfolgreich war und nur die Antwort verloren ging. Deshalb: ab dem auslösenden
Griff genau ein Versuch. Bleibt der Ausgang unklar, endet der Lauf mit409 meshcast_outcome_unclear samt Zeitpunkt als Ankerwert für die Nachschau im
Konto der Gegenseite — er entscheidet nicht und startet nicht nach.
Eine heruntergeladene Datei ist erst ein Ergebnis, wenn sie sich als Netz lesen
lässt und sich gegenüber der Eingabe plausibel verhält. Der Normalfall des
Scheiterns ist nicht die leere Datei, sondern die **Fehlerseite mit der Endung.stl**: sie existiert, sie hat eine plausible Größe, und wer nur auf Existenz
prüft, liefert sie als Form aus.
| Befund | Was passiert ist |
| --- | --- |
| form_da | lesbares Netz, umschließt die Eingabe |
| datei_fehlt / datei_leer | kein Download bzw. 0 Byte |
| html_statt_netz | Fehler- oder Anmeldeseite |
| format_unbekannt / netz_unlesbar | u. a. abgeschnittener Download (die STL-Längenformel 84 + 50·n fängt ihn) |
| keine_dreiecke / volumen_null | lesbar, aber ohne Geometrie |
| gleich_der_eingabe | die Eingabe kam Byte für Byte zurück |
| kleiner_als_eingabe | keine Form, sondern das Modell oder ein Ausschnitt |
| unverhaeltnismaessig_gross | Maßstabsfehler |
Gemessen werden Dreieckszahl, Volumen (vorzeichenbehaftete Tetraedersumme) und
Bounding-Box, für STL (binär und ASCII), OBJ und 3MF (ZIP + 3D/3dmodel.model).
Eine Datei, die nicht besteht, wird nicht mitgeliefert — auch nicht „mit
Warnung": eine Form mit Warnung sieht in einer Auftragsliste aus wie eine Form.
Sie kommt als 422 meshcast_result_implausible mit dem vollständigen Befund.
Lag keine messbare Eingabe vor (mitgelieferte Grundform), stehtohneEingabevergleich: true im Ergebnis. Das ist kein Freispruch, sondern eine
fehlende Messung — dieselbe Unterscheidung, die #1243 als ohne_abformdaten
führt.
Nicht geprüft wird Wasserdichtigkeit. Das wäre eine zweite
Geometriewahrheit neben app/meshinfo.py im Slice-Dienst.
Das ist der Zweck aus #1243/#1245: **derselbe Eingang, zwei Wege, der
Unterschied wird benannt.**
MODELL=ente.stl\nB64=$(base64 -w0 "$MODELL")# Weg A — Meshcast (dieses Addon)
curl -sS -X POST https://<aiopta>/api/v1/addons/meshcast/form \\
-H 'content-type: application/json' -H "X-API-Key: $AIOPTA_KEY" \\
-d "{\\"generator\\":\\"mold\\",\\"dateiname\\":\\"$MODELL\\",\\"inhaltBase64\\":\\"$B64\\"}" \\
> meshcast.json
# Weg B — eigene Formgeometrie im Slice-Dienst (Vorhaben #1243, Betriebsart
# "negativform"). Über die Druckzentrale, nicht über dieses Addon:
curl -sS -X POST https://<aiopta>/api/v1/addons/layery-druckzentrale/jobs/<id>/reslice \\
-H 'content-type: application/json' -H "X-API-Key: $AIOPTA_KEY" \\
-d '{"anweisung":"negativform"}' \\
> eigen.json
```
Verglichen werden die Größen, die beide Wege liefern und die dieses Addon
ohnehin misst:
| Größe | Wo sie in meshcast.json steht |
| --- | --- |
| Volumen der Form | data.pruefung.mass.volumenMm3 |
| Bounding-Box | data.pruefung.mass.groesse |
| Verhältnis Form zu Modell, je Achse | data.pruefung.vergleich.faktor |
| Dreieckszahl | data.pruefung.mass.dreieckszahl |
| Ausgabeformat | data.pruefung.format |
Der Faktor ist die aussagekräftigste Zahl: er sagt, wie viel Material die Form
gegenüber dem Urmodell kostet — und genau das entscheidet später den Preis.
Zwei Dinge, die beim Vergleichen zu beachten sind:
\n1. Bei der freien Stufe sind fünf Vergleiche je Woche möglich. Der Zähler
unter /api/v1/addons/meshcast/status sagt, wie viele davon schon gelaufen
sind.
2. **Bei den neun serverseitigen Generatoren verlässt das Vergleichsmodell das
Gerät.** Für einen Vergleichslauf mit einem echten Kundenmodell ist das eine
Datenschutzentscheidung. /mold rechnet browserseitig und ist deshalb der
unproblematischere Vergleichspartner zur eigenen Kastenform.
Begriffe werden aus #1243 übernommen und nicht neu erfunden: Negativform,
Urmodell, Trennebene, Passstifte, Angusskanal.
| Methode | Pfad | Permission | Trust |
| --- | --- | --- | --- |
| GET | /api/v1/addons/meshcast/generatoren | addons/meshcast/generators/read | standard |
| GET | /api/v1/addons/meshcast/status | addons/meshcast/status/read | standard |
| POST | /api/v1/addons/meshcast/form | addons/meshcast/form/create | highest |
form.create ist highest, und jeder der drei Gründe reicht für sich: der Lauf
startet einen Browser, er sendet bei neun von 22 Generatoren das Kundenmodell an
einen fremden Rechenserver, und er verbraucht bei der freien Stufe einen von
fünf Wochendownloads. Der Pfad liegt auf POST, damit er im Sandbox-Betrieb
(ADR-062 restricted) abgewiesen wird — ein GET, das all das tut, wäre dort
unsichtbar erlaubt.
meshcast-toolsRead-only, zwei Werkzeuge: generator_list (Katalog samt Rechenort) undstatus_get (Einrichtung, Lizenz, Wochenzähler). **Er geht überhaupt nicht ans
Netz** — beide Werkzeuge beantworten sich aus der mitgelieferten Messung und den
injizierten Slots.
Ein formerzeugendes Werkzeug gibt es bewusst nicht: ein Agent, der bei
unklarer Antwort noch einmal ruft, verbraucht den nächsten Wochendownload.
* Die undokumentierte API (Begründung oben).
* Automatisches Anmelden. Der Anmeldeweg der Gegenseite läuft über einen
fremden Dienst mit Magic-Link/OAuth; ihn blind nachzuklicken wäre Raten — und
Raten ist in diesem Addon die eine Sache, die nicht vorkommen darf.
* Ein Konto anlegen oder eine Lizenz kaufen.
* Parameter der Generatoren (Trennebenenwinkel, Passstiftmaß, Anguss-
durchmesser, Wandstärke …). Der Lauf benutzt die Voreinstellungen der Seite.
Jeder Regler wäre eine weitere Auswahlkette, die bei der nächsten Änderung
bricht — und die eigenen Regler gehören laut #1243 in betrieb.REGLER des
Slice-Dienstes, nicht hierher.
* Das Urteil über Wasserdichtigkeit. Meshcast verlangt ein manifoldes
Eingangsnetz und sagt von seiner Ausgabe, sie sei wasserdicht. Beides hier
nachzuprüfen hieße, eine zweite Geometriewahrheit neben app/meshinfo.py im
Slice-Dienst zu führen — genau die Fehlerklasse, die #1243 benennt. Gemessen
wird nur, was sich aus den Dreiecken allein ergibt.
* Attestierung. attestation.json wird ausschließlich in
ci/Jenkinsfile.addonsign signiert; der Schlüssel liegt weder im Repo noch
bei einem Entwickler. Bis dahin ein ticketgebundener Eintrag in
BEKANNTE_LUECKEN (addons#1259).
Kundenmodell ──┬─► meshcast (dieses Addon) ─────────────► Formdatei [Sonderfall, Vergleichsmaßstab]\n │\n └─► Slice-Dienst: Abformanalyse ─► Formwächter ─► Negativform / Urmodell\n │\n ▼\n layery-druckzentrale ─► Preis ─► Schnitt ─► DruckDieses Addon kennt keinen Auftrag, keinen Preis und keine Platte. Es liefert
eine Datei und ein Urteil darüber, ob sie eine ist.
Für den Kunden, der gar kein Modell hat. Er hat einen Satz oder ein Foto.
Dieses Addon macht daraus ein 3D-Modell und gibt es als STL und 3MF
heraus — sichtbar, was es kostet, und ohne dass ein fehlgeschlagener Auftrag
wie ein leeres Ergebnis aussieht.
Angebunden ist die REST-API von Meshy (api.meshy.ai, Präfix /openapi).
Alles in diesem Dokument ist am 11.08.2026 an docs.meshy.ai und an den
Nutzungsbedingungen nachgeschlagen; wo eine Aussage aus der Abwesenheit
einer Doku-Stelle folgt, steht es dabei.
1. Meshy kann keine Form. Keine Negativform, keine Boolean-Subtraktion,
kein CSG. Es ist erzeugend und nachbearbeitend, nicht parametrisch.
2. „Geprüft" heißt nicht „druckbar". Die Druckprüfung misst Netztopologie.
Wandstärke, Überhänge und Maßstab misst sie nicht.
3. Die Dateien verfallen nach drei Tagen. Wer sie behalten will, lädt sie
vorher herunter.
4. Jeder Auftrag kostet Geld. Es gibt zwei Obergrenzen, beide optional —
und wenn keine gesetzt ist, steht das ausdrücklich in der Oberfläche.
layery-druckzentrale**Betreiberentscheid vom 11.08.2026: vorerst KEINE Verbindung zur
Druckzentrale.** Das Addon steht für sich, ist für sich bedienbar und hat
keine Kante dorthin:
addonDependencies — das Manifest hat den Schlüssel überhaupt nicht;Das ist kein Versehen und keine Unfertigkeit. Wer hier eine Kante ergänzt,
muss zuerst den Test manifest.test.ts → "KEINE Abhängigkeitskante" löschen
— und liest dabei diese Begründung. Bild → 3D → STL ist ein **eigenes
Produkt**; es zuerst an einen Druckauftrag zu binden, hätte es zu einem
Zubehör gemacht, das ohne die Druckzentrale nicht installierbar ist.
Die API-Referenz führt Erzeugung (Text, Bild, Mehrbild), Nachbearbeitung
(Retexture, Remesh, Convert, Resize, UV Unwrap), Rigging/Animation und die
Druckstrecke — und an keiner Stelle etwas Parametrisches. Wer eine
Gussform oder eine Silikonform braucht, ist bei den Formen-Tickets richtig,
nicht hier. Diese Erwartung liegt nahe („es macht doch 3D") und ist falsch;
deshalb steht sie hier und im Manifest.
Der Betreiber zahlt pro Auftrag. **Eine Schleife, die unbemerkt Geld ausgibt,
ist der schlimmste Fehler, den dieses Addon machen kann.**
Dagegen stehen zwei Obergrenzen — und dass es zwei sind, hat einen
gemessenen Grund:
| Einstellung | zählt | Wirkung |
| --- | --- | --- |
| tagesgrenzeCredits | verbrauchte Credits fertiger Aufträge | die Geld-Decke, hinkt nach |
| tagesgrenzeAuftraege | angelegte kostenpflichtige Aufträge | die Schleifenbremse, greift sofort |
Der Grund: consumed_credits steht laut Doku erst am fertigen Auftrag.
Ein Auftrag in PENDING/IN_PROGRESS meldet noch nichts. Eine durchgedrehte
Schleife kann fünfzig Aufträge abschicken, bevor der erste einen Verbrauch
berichtet — die Credit-Grenze hätte bis dahin brav „0 von 500" angezeigt.
Beide sind optional und haben keinen Vorgabewert. Betreiberentscheid vom
11.08.2026: „Definierbare Obergrenze als Setting im Addon." Also:
gesetzt → durchgesetzt: der Auftrag unterbleibt mit Begründung und dem
erreichten Stand* („40 von 40"), bevor irgendetwas Kostenpflichtiges
rausgeht;
* nicht gesetzt → nichts begrenzt, aber der Zustand steht als Klartext in
der Oberfläche und in GET …/verbrauch (keineGrenzeGesetzt: true). Ein
unbegrenztes Konto, das aussieht wie ein begrenztes, ist genau der stille
Zustand, den es hier nirgends geben darf;
* unlesbar (Tippfehler) → Fehler, nicht „unbegrenzt". Sonst schaltete ein
vertipptes 5oo die Bremse still ab;
* der Zähler läuft in jedem Fall und ist ablesbar.
Der Zähler wird an der Quelle gemessen — aus Meshys eigenen
Auftragslisten, nicht aus einer lokalen Buchhaltung. Eine zweite Buchhaltung
könnte auseinanderlaufen (Neustart, ein Auftrag über die Meshy-Weboberfläche,
ein verlorener Schreibvorgang), und eine Kostenanzeige, die von der
Wirklichkeit abweicht, ist schlimmer als keine.
\nOffen gesagt, was das kostet: um die Grenze zu prüfen, muss vorher
gelesen werden. „Kein Netzruf vor der Grenze" ist also nicht wörtlich
wahr. Wahr ist: kein kostenpflichtiger Ruf, bevor die Grenze geprüft
ist. Genau so ist es getestet (
route-contract.test.ts: bei erreichterGrenze geht kein einziges POST raus).
Nachgesehen statt vermutet, in den Nutzungsbedingungen
(<https://www.meshy.ai/terms-of-use>):
| Tarif | Wem gehört die Ausgabe | Gewerbliche Nutzung |
| --- | --- | --- |
| frei | „Provider owns all right, title, and interest … in and to the AI Customer Output" | erlaubt, aber unter CC BY 4.0 — also mit Namensnennung |
| bezahlt | der Kunde behält das Eigentum und räumt Meshy nur eine Nutzungslizenz ein | ohne Namensnennung |
Für einen Druckdienstleister ist das der Unterschied zwischen „darf ich
verkaufen" und „darf ich verkaufen, wenn ich Meshy nenne". Der Hinweis steht
deshalb auch in der Oberfläche und nicht nur hier.
Die Rechte hängen am Tarif zum Zeitpunkt der Erzeugung. Ein späterer
Tarifwechsel ändert sie für bereits erzeugte Modelle nicht.
Ein erzeugtes Netz ist nicht automatisch druckbar. Es gibt zwei Stufen, und
sie versprechen sehr Unterschiedliches:
POST …/druckpruefung (/openapi/v1/print/analyze) misst genau fünf
Größen und kostet laut Doku nichts („Always 0. This endpoint is free."):
| Metrik | Stufe |
| --- | --- |
| is_watertight = false | Fehler |
| volume nicht positiv | Fehler |
| non_manifold_edges | Fehler |
| degenerate_faces | Warnung |
| holes | Warnung |
POST …/reparatur (/openapi/v1/print/repair) repariert **nur die
Topologie** hin zu einem wasserdichten Netz. Zwei Folgen, die nicht in einer
Fußnote stehen dürfen:
* 10 Credits je erfolgreicher Aufgabe;
vorhandene Texturen gehen verloren — wörtlich: „Existing textures are
removed during repair due to geometry changes."*
\n**Und die wichtigste Einschränkung: ein repariertes Netz ist kein
druckbares Teil.** Wandstärke, Überhänge und Maßstab bleiben ungeprüft. Das
ist ein Befund durch Abwesenheit: die API-Referenz nennt diese drei
Größen an keiner Stelle — sie behauptet nicht, sie nicht zu prüfen, sie
kennt sie nicht. Wer „repariert" mit „druckbar" verwechselt, verkauft ein
Modell, das erst im Schnitt auffällt. Deshalb trägt jede Antwort und
jede Ansicht das Feld
ungeprueft.
Aufträge laufen lange. Der Zustand überlebt einen Seitenwechsel, weil er
bei Meshy geführt wird und nicht hier: das Addon hat bewusst keine
zweite Auftragstabelle. GET …/auftraege liest die vier Gattungslisten und
führt sie zusammen.
Die Frist, die in der API-Doku nicht steht: die Nutzungsbedingungen sagen
*„Customer Output generated by Customers using the APIs, other than
Enterprise Customers, will be deleted three (3) days after it is generated."*
Die Modell-Adressen sind also binnen drei Tagen weg; das Antwortobjekt
trägt dafür expires_at. Ein Addon, das nur die Adresse speichert, zeigt
nach drei Tagen einen toten Link. Deshalb führt jede Antwort ablaufAm undabgelaufen mit, und ein fertiger Auftrag ohne Datei bekommt einen eigenen
Fehler (meshy_ohne_modell) statt einer leeren Dateiliste.
Der Kern dieses Addons. Diese fünf könnten sich alle als „keine Ergebnisse"
tarnen — keiner darf:
| Zustand | HTTP | code | Ging etwas raus? |
| --- | --- | --- | --- |
| nicht eingerichtet | 503 | meshy_not_configured | nein, gar nichts |
| Einstellung unlesbar | 503 | meshy_einstellung_ungueltig | nein, gar nichts |
| Tagesgrenze erreicht | 429 | meshy_grenze_erreicht | gelesen ja, angelegt nein |
| Meshy nicht erreichbar | 502 | meshy_unreachable | ja, ohne Antwort |
| Ausgang unklar | 409 | meshy_ausgang_unklar | ja — nicht wiederholen |
| fertig, aber ohne Datei | 409 | meshy_ohne_modell | ja |
| erreichbar und leer | 200 | — | ja, es ist wirklich leer |
Dazu: meshy_auth_fehlgeschlagen (502), meshy_kontingent (402),meshy_abgelehnt (400), meshy_auftrag_unbekannt (404),meshy_gattung_fehlt (400), meshy_wunsch_ungueltig (400),meshy_upstream_error (502).
Kein Wiederholversuch auf einem kostenpflichtigen Pfad. Bleibt der
Ausgang unklar, sagt die Antwort genau das — mit dem Zeitpunkt als Ankerwert
für die Nachschau in der Auftragsliste. Das Addon misst und berichtet, es
entscheidet nicht.
| Methode | Pfad | Berechtigung | Kostet |
| --- | --- | --- | --- |
| GET | …/auftraege | auftraege/lesen | nein |
| POST | …/auftraege | auftraege/erzeugen | ja |
| GET | …/auftraege/{id}?art=… | auftraege/lesen | nein |
| POST | …/auftraege/{id}/druckpruefung | pruefung/starten | nein (Doku: „Always 0") |
| POST | …/auftraege/{id}/reparatur | reparatur/starten | ja, 10 Credits |
| GET | …/verbrauch | auftraege/lesen | nein |
art ist beim Einzelabruf Pflicht (text, bild, pruefung,reparatur). Meshy hat vier getrennte Endpunktfamilien und keine
gattungsübergreifende Nachschlagestelle; wer die Gattung nicht kennt, müsste
vier Rufe raten. Die Gattung steht in jeder Zeile der Auftragsliste.
| Capability | Tier | Begründung |
| --- | --- | --- |
| addons.meshy.auftraege.lesen | elevated | Bounded Egress mit hinterlegtem Schlüssel |
| addons.meshy.auftraege.erzeugen | highest | gibt Geld aus, nicht zurücknehmbar |
| addons.meshy.pruefung.starten | elevated | kostet laut Doku nichts, legt aber einen Auftrag an |
| addons.meshy.reparatur.starten | highest | 10 Credits und Texturverlust |
Wer messen darf, darf deshalb noch nicht bezahlen und Texturen verlieren —
deshalb sind Prüfen und Reparieren getrennt.
Alle drei anlegenden Routen liegen auf POST, auch die kostenlose Prüfung.
Nur ein mutierendes Verb wird auf ADR-062-Stufe restricted abgewiesen
(isMethodAllowedForTrust); ein Pfad, der bei einem Fremddienst etwas anlegt
und an einem GET hinge, wäre im Sandbox-Betrieb still erlaubt.
Alles über die Aiopta-Oberfläche, nichts von Hand in einer Datei. **Kein Feld
hat einen Vorgabewert** — die Addons gehen an fremde Betreiber (#1220, #1226,
#1215 sind genau daran gescheitert).
| Schlüssel | Typ | Pflicht | Leer bedeutet |
| --- | --- | --- | --- |
| apiKey | password | ja | jede Route antwortet 503, ohne Netzruf |
| modell | text | nein | ai_model wird nicht gesendet, Meshy entscheidet |
| polygonzahl | text | nein | target_polycount wird nicht gesendet |
| tagesgrenzeCredits | text | nein | unbegrenzt — und wird als unbegrenzt angezeigt |
| tagesgrenzeAuftraege | text | nein | unbegrenzt — und wird als unbegrenzt angezeigt |
„Nicht gesendet" ist nicht dasselbe wie „auf einen Vorgabewert gesetzt". Der
Unterschied ist messbar: meshy-client.test.ts prüft, dass das Feld im
Anfragekörper fehlt.
modell nimmt meshy-5, meshy-6, meshy-7 oder latest. **meshy-4 ist
in der aktuellen Referenz nicht mehr wählbar** und wird hier benannt
abgelehnt, statt es an Meshy durchzureichen und sich nach dem Netzruf ablehnen
zu lassen.
api.meshy.ai fest im Code stehtDas sieht aus wie das DEFAULT_BASE_URL, an dem spoolman (#1226) undoctoprint-proxy (#1215) hängengeblieben sind, ist aber der umgekehrte Fall:
* Dort war die Adresse der Wirt des Betreibers. Ließ ein fremder Betreiber
das Feld leer, rief sein Server still die Produktivinstanz eines anderen
Kunden auf.
* Hier ist die Adresse der Anbieter selbst. Es gibt genau einen
Meshy-Endpunkt; ihn einstellbar zu machen hieße, ein Feld anzubieten, in das
nur ein Umleitungsangriff etwas anderes schreiben könnte.
Getrennt wird über den Schlüssel — und der ist Pflicht und hat keine
Vorgabe. Dasselbe Muster fährt revenue-cat. config.test.ts pinnt beide
Hälften: die feste Anbieteradresse und die Abwesenheit jedes
Vorgabewerts.
meshy-toolsDrei read-only Werkzeuge: meshy_auftrag_liste, meshy_auftrag_lesen,meshy_verbrauch.
Kein erzeugendes, kein prüfendes und kein reparierendes Werkzeug. Erzeugen
und Reparieren geben Geld aus, und die Meshy-API kennt keinen
Idempotenzschlüssel — ein Agent, der bei unklarer Antwort noch einmal ruft,
bezahlt zweimal. Auch die kostenlose Prüfung ist kein Werkzeug: sie legt einen
Auftrag bei einem fremden Dienst an, und „kostenlos" ist eine Zusage des
Anbieters, keine Eigenschaft des Protokolls. Alle drei Pfade laufen
ausschließlich über die API-Routen mit eigener Berechtigung.
Der Test meshy-tools-mcp.test.ts prüft das nicht als Aufzählung, sondern
über tools/list: kein Ruf irgendeines Werkzeugs ist ein POST. Ein später
ergänztes Werkzeug fällt sofort auf.
Ohne AIOPTA_CREDENTIAL_APIKEY fällt jedes Werkzeug fail-closed aus — und
zwar ohne fetch, nicht nur mit einer Fehlermeldung. Handshake undtools/list laufen ohne jede Env (Conformance C3).
Kein Test läuft gegen die echte API. Sie kostet Geld, und ein Testlauf,
der ein Konto belastet, ist einer, den niemand zweimal startet. Der globalefetch ist überall gestubbt; ein durchgerutschter echter Ruf fällt als
„fetch not stubbed" auf.
| Datei | Was sie festhält |
| --- | --- |
| config.test.ts | keine Vorgabe, kein fetch ohne Schlüssel, die Adresse am Quelltext gemessen |
| kostengrenze.test.ts | der Zähler, beide Grenzen, „leer ≠ null ≠ kaputt", und der Nachweis, dass die Credit-Grenze nachhinkt |
| meshy-client.test.ts | v2 vs. v1, fehlende Felder im Körper, Millisekunden, ein Versuch je Kostenpfad |
| errors.test.ts | die fünf Tarnungen tragen fünf verschiedene Codes |
| route-contract.test.ts | anon401, getrennte Rechte, 429 ohne einziges POST, kein Schlüssel in einer Antwort |
| manifest.test.ts | Adoptions-Standard, kein default, keine Kante zur Druckzentrale |
| trust.test.ts | ADR-062: auf restricted läuft kein anlegender Pfad |
| page.test.tsx | sechs unterscheidbare Bilder, „keine Obergrenze gesetzt" als Klartext |
| meshy-tools-mcp.test.ts | fail-closed, und kein Werkzeug setzt ein POST ab |
attestation.json fehlt. Signiert wird ausschließlich im Auftragci/Jenkinsfile.addonsign mit der Credential aiopta-addon-signing-key; der
Schlüssel liegt weder im Repo noch bei einem Entwickler. Bis dahin steht ein
ticketgebundener Eintrag in scripts/check-addon-adoption.cjs
(BEKANNTE_LUECKEN), dessen Muster ausschließlich auf^attestation\\.json missing passt. **Nach dem Signieren muss dieser Eintrag
weg** — veralteteAusnahmen macht sonst rot.
Alles am 11.08.2026 abgerufen:
\nAuthorization: Bearer msy_…mode: previewconsumed_credits, expires_atstl/3mf, target_polycount 100–300000{ "balance": <int> }Plan motorcycle tours and export a GPX 1.1 file for your navi (Garmin /
TomTom / Calimoto). Round-trip or one-way, with waypoints, sized by target
distance or duration, with a curviness level, avoid-highway (or
"highway-until-X, then curvy/passes"), and prefer-passes. Built on ADR-037.
v1.1 adds: POIs along the route (fuel/food/viewpoint… from
OpenStreetMap/Overpass, kept only inside a corridor around the planned line and
emitted as GPX waypoints with navi symbols), multi-day tours split into day
stages with one GPX per stage (download a single day), and an **elevation
profile** (Höhenprofil — ascent/descent/min/max + a distance↔elevation series).
- Routing engine = BRouter container (ADR-009). BRouter is an open-source
router ideal for curvy moto routes (it avoids motorways and biases toward
winding roads / passes via profiles). The addon declares it as an Aiopta-managed
container, booted at install, and reaches it only via the Aiopta-internal URL —
never a hard-coded host (src/lib/brouter.ts →
getContainerAddonInternalUrl("moto-routeplanner")).
- Fallback. When the container is absent, an optional owner-keyed
GraphHopper / OpenRouteService Directions API serves the route
(ROUTING_FALLBACK_API_KEY in Aiopta addon-config — sent server-side, never
logged). If neither is available, plan calls return a clear 503 and
/status reports it; the addon never crashes and never calls a default host.
- Planning is pure + tested. Parameters → a BRouter profile (profile.ts),
round-trip loops generated by a documented waypoint-ring heuristic
(roundtrip.ts), and a hand-rolled GPX 1.1 serializer (gpx.ts). No routing or
GPX npm dependency is added.
- v1.1 POIs along the route. A keyless Overpass (OpenStreetMap) query
(overpass.ts, the only POI I/O — server-side, owner-overridable endpoint, any
private-mirror key sent as a header and never logged) fetches candidates in the
track's bounding box; a pure corridor filter (poi.ts) keeps only those
within poiCorridorM of the line, annotates offset + along-route distance, and
emits them as GPX <wpt>s with category symbols. A POI-source outage is
best-effort: the route + GPX still come back (with a poiError note).
- v1.1 multi-day stages + elevation. A pure splitter (stages.ts) cuts
the routed track into day stages near a perDayKm target (or a fixed
stageCount) — contiguous slices sharing each boundary point — and each stage is
serialized to its own GPX. A pure profiler (elevation.ts) turns the
track's elevations into a Höhenprofil (jitter-suppressed ascent/descent, min/max,
max grade, a down-sampled distance↔elevation series). Saved tours re-derive
stages/elevation from the stored GPX (a tolerant parseGpxTrackPoints) with no
re-routing.
start (required), optional destination (required for one-way; defaults to the
start for a round-trip) and waypoints; tourType (round-trip / one-way);curviness (straight / balanced / curvy / very-curvy); highwayMode
(avoid / allow / until-waypoint + highwayUntilIndex); targetDistanceKm
or targetDurationMin (round-trip sizing); preferPasses; name, save.
v1.1: includePois + poiCategories
(fuel/food/cafe/viewpoint/attraction/hotel/repair) + poiCorridorM;multiDay + perDayKm or stageCount. POST /plan then also returns pois,poiError, elevation (samples + stats) and, when multiDay, stages (with
a per-stage gpx).
The acceptance case — a curvy round-trip by target distance, no highway —
produces a valid, downloadable GPX. Curviness and highway mode demonstrably change
the BRouter profile that reaches the engine.
Base: /api/v1/addons/moto-routeplanner. All routes are userRoute-auth-gated;
the per-agent capability is addons/moto-routeplanner/*.
| Method + path | Purpose |
|---------------|---------|
| GET /status | Engine/container availability + saved-tour count |
| POST /plan | Plan a tour → route + GPX (optional save:true) |
| GET /tours | List saved tours |
| POST /tours | Plan and save a tour |
| GET /tours/{id} | Fetch one saved tour (params + GPX + elevation profile) |
| GET /tours/{id}/gpx | Download the GPX (application/gpx+xml) |
| GET /tours/{id}/stages | v1.1 List the saved tour's day stages |
| GET /tours/{id}/stages/{n}/gpx | v1.1 Download one stage's GPX (application/gpx+xml) |
| DELETE /tours/{id} | Delete a saved tour |
Saved tours live in one addon-local table (moto_routeplanner_tours), created
in install() and dropped in uninstall() — no core-schema impact.
Per-user isolation (#147 / ADR-054): moto_routeplanner_tours carries user_id;
the server stamps the owner from the authenticated caller on save (a client-supplied
owner is ignored), and every list/read/GPX-download/delete is scoped to the caller viascopedStore. A tour id owned by another user returns 404 (no existence leak) — you
only ever see and act on your own saved tours, and the widget's "latest" is your own.
A management page (Tools section) sets start/destination/waypoints + curviness,
highway and target-distance controls + a round-trip toggle and prefer-passes,
computes a route, shows a summary (distance / duration / ascent / waypoint list)
and downloads the GPX, plus a saved-tours list. A dashboard widget shows the
saved-tour count, the latest tour and engine readiness. Light + Dark, mobile,var(--color-*).
\nNo interactive map yet. No map library is currently an Aiopta
dependency, and the project's no-new-dep rule forbids adding one, so the page
ships a functional coordinate-input + route-summary UI. An interactive map is
parked in
docs/OPEN-DECISIONS.mdas a follow-up.
1. BRouter image + rd5 region data (brouter-routing-image /
brouter-rd5-region): build/publish the BRouter image and provision the
region-selectable OSM segment data (disk).
2. Fallback Directions key (routing-fallback-api-key): optionally set
ROUTING_FALLBACK_API_KEY (+ ROUTING_FALLBACK_PROVIDER) for the
container-absent fallback.
3. Overpass endpoint (v1.1, optional): POIs use the public Overpass API by
default (keyless). To point at a self-hosted/rate-limited mirror, set
OVERPASS_API_URL (+ optional OVERPASS_API_KEY, sent server-side as a header,
never logged) in Aiopta addon-config.
4. Map library (moto-routeplanner-map-lib): parked until/unless a map lib is
a dependency.
Until (1) or (2) is provisioned, /status reports the engine not-configured and
plan calls return a clear 503.
tests/unit/ (WSL node22): GPX 1.1 validity (gpx.test.ts), param→profile
mapping (profile.test.ts), round-trip distance bounds + geo helpers
(roundtrip.test.ts), the engine client incl. the no-engine 503 + container URL +
fallback (brouter.test.ts), the planner incl. the acceptance GPX + highway-until
two-leg routing (planner.test.ts), manifest/dual-registration (manifest.test.ts),
and the saved-tour per-user isolation (isolation.test.ts).
v1.1 tests: the elevation profile (elevation.test.ts), multi-day staging
(stages.test.ts), the POI corridor filter + category model (poi.test.ts), the
Overpass transport incl. key-never-leaked + 502 paths (overpass.test.ts), the
GPX POI waypoints + trackpoint parser (gpx-v11.test.ts), the planner
orchestration of POIs/elevation/stages with the engine + Overpass mocked
(planner-v11.test.ts), and per-user isolation of the new stage routes
(isolation-v11.test.ts).
Bindet eine vorhandene, externe n8n-Instanz als connect-Addon in Aiopta
ein: Workflows auflisten samt Zustand (aktiv/inaktiv), **Ausführungen
einsehen (was läuft dort noch?) und einen Workflow starten**.
Lesen steht im Vordergrund. Starten ist genau eine Schaltfläche je Zeile —
und nur dort, wo die n8n-API es hergibt.
Ticket: Aiopta/aiopta-addons#1222.
workflow-builder — gemessen, nicht argumentiertaddons/workflow-builder erwähnt n8n, ist aber keine n8n-Anbindung. Der
Befund am Quelltext (Stand origin/develop, 2026-08-10):
| Frage | workflow-builder | dieses Addon |
|---|---|---|
| Was ist es? | eine eigene, Aiopta-interne Ausführungs-Engine | eine Anbindung an eine externe Instanz |
| Externe Hosts | verboten — assertSameOrigin() weist jeden nicht-Aiopta-Origin ab | genau das ist der Zweck |
| Kennt X-N8N-API-KEY? | nein, kein Vorkommen | ja, das ist der Auth-Kopf |
| Kennt einen n8n-Endpunkt? | nein, kein Vorkommen | /api/v1/workflows, /api/v1/executions |
| Führt selbst aus? | ja (Schritte: http/agent/condition/delay) | nein — n8n führt aus |
Der Kommentar in addons/workflow-builder/src/lib/engine.ts sagt es
wörtlich: *"the engine NEVER makes an arbitrary outbound request (ADR-009:
addons orchestrate via the Aiopta API/gateway, never external hosts)"*. Das
Wort „n8n" steht dort ausschließlich als Vergleich („n8n-lite scoped to
this platform").
Damit ist ein Addon n8n eine Ergänzung, keine Dublette: das eine baut
Automatisierung in Aiopta, das andere macht sichtbar und bedienbar, was
außerhalb in n8n läuft.
\nDie Namensfalle aus der Addon-Vorlagen-Doku („n8n heißt
workflow-builder")beschreibt die Analogie, nicht die Anbindung. Sie hat in diesem Projekt
schon einmal zu einem falschen Plan geführt.
Browser/Agent ──HTTPS──▶ Aiopta (dieses Addon) ──HTTPS──▶ externe n8n-Instanz\n ├─ Dashboard (native DS-Seite) /addons/n8n\n ├─ API-Routen (userRoute) /api/v1/addons/n8n/…\n └─ MCP-Server (n8n-tools) read-only- Natives Dashboard (src/page.tsx, ui.mode: "aiopta"): Workflows mit
Zustand und Startweg, Ausführungen mit Statusfilter. Ausschließlich
@aiopta/ui-Komponenten; der Browser kontaktiert n8n nie direkt.
- API-Routen (src/app/api/v1/addons/n8n/*): zentrale Auth über
userRoute (Session-Cookie oder Bearer/X-API-Key Agent-Key).
- Client (src/lib/n8n-client.ts): injizierbarer fetch-Seam (Muster
spoolman-client.ts), damit kein Unit-Test je das Netz anfasst.
- Konfiguration (src/lib/config.ts): baseUrl + apiKey (BYOK,
password-Slot). Der Schlüssel verlässt den Server nie — auch nicht
maskiert in einem Fehlertext.
\n„Addons in Aiopta: keine Defaults für Umgebungen, Namen und so - das wird
später vertrieben. Es soll als Addon auch für andere Nutzer gehen, ohne
meine Domain mitzugeben." — Betreiber, 10.08.2026
Deshalb gilt hier hart:
\n- kein default im settingsSchema (gepinnt in manifest.test.ts),
- kein Rückfall im Code auf irgendeine URL (gepinnt in config.test.ts,
inklusive einer Prüfung am Quelltext, dass dort kein Hostname steht),
- leere Einstellung → sprechender Fehler, kein Netzruf (gepinnt in
route-contract.test.ts: fetch wurde nachweislich nie gerufen),
- Beispiel-URLs stehen in der description, nie in default.
Erhoben am 2026-08-10 an der OpenAPI-Beschreibung der n8n Public API
(packages/cli/src/public-api/v1/openapi.yml, info.version 1.1.1):
- Workflow-Pfade sind /workflows, /workflows/{id},
/workflows/{id}/activate, /deactivate, /archive, /transfer,
/tags.
- Es gibt keinen Pfad /workflows/{id}/execute und keinen /run.
- Auth: Kopf X-N8N-API-KEY, Basis /api/v1.
- Blättern: ?limit&cursor rein, { data, nextCursor } raus; limit ist
bei 250 gedeckelt.
Folge: Ein Workflow lässt sich von außen nur über seinen
Webhook-Trigger starten. Dieses Addon liest dafür path und httpMethod
aus dem n8n-nodes-base.webhook-Knoten der Workflow-Definition und ruft<basis>/webhook/<pfad> — den Produktions-Pfad, nicht webhook-test
(der existiert nur, solange jemand den Editor offen hat).
Was das für den Betrieb heißt, steht in der Liste, nicht erst nach einem
Klick: jede Zeile trägt startable und, wenn nicht, den Grund.
| Lage | startable | Grund |
|---|---|---|
| aktiver Workflow mit Webhook-Knoten | true | — |
| Workflow ohne Webhook-Knoten | false | kein Startweg; die Public API kennt kein Ausführen |
| inaktiver Workflow | false | der Produktions-Webhook ist nicht registriert |
Ein Webhook-Aufruf ist nicht idempotent — n8n kennt dafür keinen
Idempotenzschlüssel. Bleibt der Ausgang unklar (Zeitgrenze,
Verbindungsabbruch), antwortet die Route mit 409 run_unclear und liefertattemptedAt als Ankerwert mit. Der Abgleich läuft überGET /executions?workflowId=…. Das Addon **misst und berichtet, es
entscheidet nicht** — dieselbe Regel wie in spoolman.
Bei den elf LayerY-Workflows ist das kein akademischer Punkt: ein zweiter
Versuch kann eine zweite Bestellung, eine zweite Mail, eine zweite Buchung
auslösen.
Der Webhook-Körper landet als Eingabe im Workflow und im
Ausführungsprotokoll jedes Laufs. Ein X-N8N-API-KEY dort hieße: der
Instanz-Schlüssel liegt im Klartext in der Lauf-Historie. Er geht
ausschließlich an /api/v1/… (gepinnt in n8n-client.test.ts undroute-contract.test.ts).
Basis: https://<instanz>/api/v1/addons/n8n
| Ziel | Methode + Pfad | Permission |
|---|---|---|
| Workflows mit Zustand + Startweg | GET /workflows | addons/n8n/workflows/read |
| Ein Workflow mit Startbarkeit | GET /workflows/{id} | addons/n8n/workflows/read |
| Workflow starten | POST /workflows/{id}/run | addons/n8n/workflows/run |
| Ausführungen einsehen | GET /executions | addons/n8n/executions/read |
| Eine Ausführung | GET /executions/{id} | addons/n8n/executions/read |
# was gibt es, und was ist aktiv?\ncurl -s -H "Authorization: Bearer $AIOPTA_API_KEY" \\\n "https://<instanz>/api/v1/addons/n8n/workflows?active=true"# was läuft dort gerade noch?
curl -s -H "Authorization: Bearer $AIOPTA_API_KEY" \\
"https://<instanz>/api/v1/addons/n8n/executions?status=running"
# einen Workflow starten
curl -s -X POST -H "Authorization: Bearer $AIOPTA_API_KEY" \\
-H 'content-type: application/json' -d '{"payload": {"quelle": "aiopta"}}' \\
https://<instanz>/api/v1/addons/n8n/workflows/wf-1/run
```
code)| Situation | Status | code | Netzruf? |
|---|---|---|---|
| nichts eingestellt | 503 | n8n_not_configured | nein |
| Basis-URL unbrauchbar | 503 | n8n_invalid_base_url | nein |
| Schlüssel abgelehnt | 502 | n8n_auth_failed | ja |
| Instanz nicht erreichbar | 502 | n8n_unreachable | ja |
| Ressource unbekannt | 404 | n8n_not_found | ja |
| fremder Upstream-Status | 502 | n8n_upstream_error | ja |
| Workflow inaktiv | 409 | workflow_inactive | nur Lesen |
| kein Webhook-Trigger | 409 | no_webhook_trigger | nur Lesen |
| Start unklar | 409 | run_unclear | ein Startruf |
Ein leeres Ergebnis (200 { workflows: [] }) sieht nachweislich anders
aus als ein Ausfall — und ein nicht eingerichtetes Addon sieht anders aus
als beides.
tierDas sind zwei verschiedene Achsen, und ADR-062 ist nicht ADR-060:
\n1. ADR-062 trusted | standard | restricted — instanzweit, vom Admin
gesetzt, steht nicht im Manifest, durchgesetzt über
isMethodAllowedForTrust.
2. capabilityDeclarations[].tier — die deklarative Absicht dieses Addons.
Auf restricted läuft das Lesen weiter und das **Starten wird
abgewiesen** — deshalb liegt der Startpfad auf POST. Der n8n-Webhook-Knoten
selbst darf auf GET stehen; die Aiopta-Route bleibt trotzdem POST, sonst
wäre das Addon nicht sandboxbar. Gepinnt in tests/unit/trust.test.ts gegen
die echte Core-Funktion.
n8n-tools, read-only)workflow_list, workflow_get, execution_list, execution_get.
Es gibt kein startendes Tool — und das ist eine Entscheidung, keine
Lücke: ein Agent, der bei unklarer Antwort noch einmal ruft, lässt den
Workflow ein zweites Mal laufen. Der startende Pfad läuft ausschließlich über
die API-Route mit eigener, höchster Trust-Stufe.
includeData der Ausführungen wird ebenfalls nicht geliefert: diese Daten
tragen die Nutzlast jedes durchlaufenen Knotens.
Authentifizierung ausschließlich über die core-injizierten SlotsAIOPTA_CONFIG_BASEURL / AIOPTA_CREDENTIAL_APIKEY — nie als
Tool-Argument. Der Server bringt keine vorbelegte Instanz mit; fehlt ein
Slot, sagt das Tool das und ruft nichts ab.
1. In n8n unter Settings → API einen Public-API-Schlüssel erzeugen.
2. In Aiopta unter Einstellungen → Addons → n8n eintragen:
- n8n-Basis-URL — die Wurzel der Instanz, z. B.
https://n8n.example.com (ohne /api/v1, ohne Pfad),
- n8n-Public-API-Schlüssel.
3. /addons/n8n öffnen.
Ohne diese beiden Werte antwortet jede Route mit 503 n8n_not_configured —
und ruft nichts ab.
attestation.json fehlt. Signiert wird ausschließlich im Jenkins-Auftragci/Jenkinsfile.addonsign mit der Credential aiopta-addon-signing-key; der
Schlüssel liegt weder im Repo noch bei einem Entwickler. Bis dahin deckt ein
ticketgebundener Eintrag in BEKANNTE_LUECKEN
(scripts/check-addon-adoption.cjs, addons#1222) eng nur den Befundattestation.json missing.
Danach muss der Eintrag n8n aus BEKANNTE_LUECKEN wieder entfernt
werden — eine Ausnahme, die nichts mehr deckt, macht den Lauf rot
(veralteteAusnahmen).
Universal notification dispatch to AI agent backends
\nnotificationsDieses Addon benötigt folgende Secrets/Provider-Konfiguration (Settings → Credentials bzw. Provider-Store, nie in addon.json):
\nHERMES_API_KEYOPENCLAW_API_KEYPI_AGENT_API_KEY| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/notifications/channels |
| GET, POST | /api/v1/addons/notifications/config |
| GET | /api/v1/addons/notifications/history |
| POST | /api/v1/addons/notifications/send |
| POST | /api/v1/addons/notifications/test |
| GET, PUT | /api/v1/addons/notifications/ntfy/settings |
| POST | /api/v1/addons/notifications/ntfy/test |
Der bevorzugte self-hosted Push-Pfad (statt FCM). Push geht per HTTP-POST an ein pro-User-Topic, das serverseitig aus der userId abgeleitet wird (<prefix>-sha256(userId)[:24]) — nie ein Client-Wert. Ein Push für User A kann niemals an B's Topic adressiert werden. Der Mobile-Wrapper abonniert via UnifiedPush dasselbe Topic — ein POST erreicht Web und Android ohne Firebase. FCM bleibt optional/deprecated, aber funktionsfähig.
Konfiguration (instance-global, Aiopta addon-config):
\n| Key | Zweck | Default |
|---|---|---|
| NTFY_SERVER_URL | self-hosted ntfy-Server (oder ntfy.sh). Owner-Entscheidung (OPEN-DECISIONS Block H). | https://ntfy.sh |
| NTFY_AUTH_TOKEN | optionaler Bearer-Token für geschützten Server (Secret). | — |
| NTFY_TOPIC_PREFIX | Namespace-Prefix für pro-User-Topics. | mc |
Solange kein Server gesetzt ist, degradiert der Kanal graziös (ntfy not configured, kein Crash).
Per-User: Jeder User aktiviert ntfy in seinen Notification-Settings (GET/PUT …/ntfy/settings, opt-in + Min-Priorität); der State liegt user-scoped (scopedStore, ADR-054). POST …/ntfy/test sendet einen Test-Push nur an das eigene Topic des Callers.
Per-User OctoPrint-Anbindung: BYOK URL+API-Key pro Drucker, Live-Status/Jobs/
Temperatur/Webcam, G-Code-Queue und Multi-Drucker. Brückt lesend zum
openscad-generator-Addon (generierte Modelle in die Queue), ohne
openscad-generator zu verändern. Lokale SQLite ist die Quelle der Wahrheit
(ADR-054).
octoprint/addons/octoprintBYOK: pro Drucker werden eine OctoPrint-Basis-URL und ein Application API-Key
benötigt (im Frontend oder via POST /printers). Die Credentials liegen
per-User scoped in der lokalen SQLite (ADR-054) — sie werden nie hardcodiert
und nur für den jeweiligen Caller gelesen. Live-Daten (Status/Jobs/Temp/Webcam)
werden on-demand von der Instanz des Nutzers geholt und nicht persistiert.
| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/octoprint/printers |
| GET, PATCH, DELETE | /api/v1/addons/octoprint/printers/[id] |
| GET | /api/v1/addons/octoprint/jobs?printerId= |
| GET | /api/v1/addons/octoprint/temperature?printerId= |
| GET | /api/v1/addons/octoprint/webcam?printerId= |
| GET, POST | /api/v1/addons/octoprint/queue |
| PATCH, DELETE | /api/v1/addons/octoprint/queue/[id] |
| POST | /api/v1/addons/octoprint/bridge/openscad |
", "byteSize": 1824 } } }, { "id": "octoprint-proxy", "uuid": "25f29dbd-f4f1-4b2b-82d6-907de0ccb930", "name": "OctoPrint Sync Proxy", "version": "2.0.1", "description": "Kapselt den extern laufenden OctoPrint Sync Proxy (Python-FastAPI, LAN-intern) in Aiopta: natives Dashboard (Status-Karten OctoPrint/Git/USB/G-Code-Kette, Job-Liste mit Fortschritt, Retry- und USB-Sync-Aktionen), API-Routen mit zentraler Auth und HMAC-Grant-Minting, Versionshistorie und Datei-Download je Job, OctoPrint-kompatible API für OrcaSlicer (Upload/Listing/Download via Aiopta Agent-API-Key) sowie ein MCP-Server (proxy-tools). Jeder Job trägt zusätzlich den Stand der G-Code-Nachbearbeitungskette (unverändert/geändert/aus) samt Kurzbericht.", "author": "Aiopta", "icon": "🖨️", "capabilities": [ "octoprint", "sync-proxy", "jobs", "usb-sync", "orcaslicer", "3d-printing", "gcode-postprocessing", "git-history", "file-download" ], "tags": [], "download": "/artifacts/octoprint-proxy-2.0.1.zip", "sha256": "73e3de8524132e6632eb1d4fe9db319f93fc1db6d3cf5bd628adf5aaacd6678d", "size": 205519, "page": { "id": "octoprint-proxy", "path": "/addons/octoprint-proxy", "name": "OctoPrint Sync", "icon": "🖨️", "section": "Tools", "component": "@addons/octoprint-proxy/src/page" }, "deprecated": false, "endpoints": [ "/api/v1/addons/octoprint-proxy/status", "/api/v1/addons/octoprint-proxy/jobs", "/api/v1/addons/octoprint-proxy/jobs/{id}", "/api/v1/addons/octoprint-proxy/jobs/{id}/versions", "/api/v1/addons/octoprint-proxy/jobs/{id}/download", "/api/v1/addons/octoprint-proxy/jobs/{id}/retry", "/api/v1/addons/octoprint-proxy/kette/abgelehnt/quittieren", "/api/v1/addons/octoprint-proxy/usb/sync", "/api/v1/addons/octoprint-proxy/api/version", "/api/v1/addons/octoprint-proxy/api/files/local", "/api/v1/addons/octoprint-proxy/api/files/local/{name}", "/api/v1/addons/octoprint-proxy/downloads/files/local/{name}" ], "skills": [ { "name": "octoprint-proxy-read", "displayName": "OctoPrint Sync Proxy: Status & Jobs lesen", "description": "Liest Service-Status (OctoPrint/Git/USB/G-Code-Kette), die Sync-Job-Liste inklusive Kettenstand, das Job-Detail mit vollem Kettenbericht und die Git-Versionshistorie einer Datei über die Addon-API. Reiner Lesezugriff.", "permissions": [ "addons/octoprint-proxy/read" ], "endpoint": "/api/v1/addons/octoprint-proxy/status", "scripts": [] }, { "name": "octoprint-proxy-write", "displayName": "OctoPrint Sync Proxy: Retry, USB-Sync & Ablehnungen quittieren", "description": "Setzt fehlgeschlagene Sync-Targets eines Jobs zurück (Retry), startet manuelle USB-Syncs und quittiert Uploads, die die G-Code-Kette abgelehnt hat, über die Addon-API.", "permissions": [ "addons/octoprint-proxy/read", "addons/octoprint-proxy/write" ], "endpoint": "/api/v1/addons/octoprint-proxy/usb/sync", "scripts": [] } ], "mcpServers": [ { "id": "proxy-tools", "displayName": "OctoPrint Sync Proxy tools", "description": "MCP-Tools für den externen OctoPrint Sync Proxy: Status (OctoPrint/Git/USB/G-Code-Kette) und Job-Liste lesen, Job-Details inklusive vollem Kettenbericht abrufen und als einziges schreibendes Tool einen Job-Retry auslösen. Authentifiziert sich per HMAC-Grant (grantSecret) oder Fallback per proxyApiKey; beides wird core-seitig aus den deklarierten Settings-Slots aufgelöst.", "transport": "stdio", "runtime": "node", "entry": "proxy-tools/server.mjs", "permissions": [ "addons/octoprint-proxy/job/retry", "addons/octoprint-proxy/read" ], "toolPolicy": { "mode": "write", "allowDestructive": false }, "configRefs": [ "baseUrl" ], "credentialRefs": [ "grantSecret", "proxyApiKey" ], "archiveEntry": "octoprint-proxy/mcp/servers/proxy-tools/server.mjs", "sha256": "ee6141dccac933d74fb29fc8db970c78ea60bffbb3db848c749a849a217589c2", "size": 14628, "descriptorVersion": 1 } ], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README manuell gepflegt (addon.json + Routen als Quelle).
Kapselt den extern laufenden OctoPrint Sync Proxy (Python/FastAPI,
LAN-intern) in Aiopta — ohne den Dienst selbst zu verändern und ohne ihn
nach außen zu exponieren.
\nKeine Vorgabewerte für fremde Wirte. Die Basis-URL des Proxy ist eine
Pflichteinstellung ohne
default. Solange sie leer ist, ruft dasAddon nichts auf, sondern antwortet mit „baseUrl ist nicht konfiguriert"
(Dashboard-Routen 500, OrcaSlicer-Endpunkte 503, MCP-Tools
„nicht konfiguriert"). Adressen in dieser Datei sind Beispiele.
Browser/OrcaSlicer ──HTTPS──▶ Aiopta (dieses Addon) ──LAN──▶ Sync Proxy (baseUrl, z.B. proxy.lan:8000)\n ├─ Dashboard (native DS-Seite) /status, /api/proxy/*\n ├─ API-Routen (userRoute + Grant) /api/proxy/*\n ├─ Orca-API (X-Api-Key, statisch) /api/version, /api/files/local*,\n │ /downloads/files/local/*\n └─ MCP-Server (proxy-tools) /status, /api/proxy/jobs*- Natives Dashboard (src/page.tsx, ui.mode: "aiopta"): Status-Karten
(OctoPrint/Git/USB und G-Code-Kette), Job-Liste (neueste oben) mit
Fortschrittsbalken, Retry- und USB-Sync-Aktionen. Ausschließlich
@aiopta/ui-Komponenten. Der Browser kontaktiert den Proxy nie direkt.
- G-Code-Nachbearbeitungskette: der Proxy lässt seit dem Ausbau der
Kette jeden Upload durch eine Reihe von Schritten laufen (u. a. Kürzen zu
langer M486-Objektnamen). /status führt sie als vierte Station
neben OctoPrint/Git/USB (aktiv, Schritte, Konfigurationsfehler, Zähler
geändert/unverändert, abgelehnte Uploads); jeder Job trägt seinen
Kettenstand, das Job-Detail zusätzlich den vollen Bericht. Das Addon
reicht beides unverändert durch — es filtert die Felder nicht.
- API-Routen (src/app/api/v1/addons/octoprint-proxy/*): zentrale Auth
via userRoute (Session-Cookie oder Bearer/X-API-Key Agent-Key). Danach
mintet das Addon einen HMAC-Grant (`X-Aiopta-Grant:
v1.<base64url(payload)>.<base64url(hmac)>; Payload {aud, caps, exp,
iat, sub}; HMAC-SHA256 mit grantSecret`; TTL 110 s) — Implementierung in
src/lib/grant.ts, byte-kompatibel zur Proxy-Referenz app/grant.py.
Fallback: statischer X-Api-Key (proxyApiKey).
- OrcaSlicer nutzt den Proxy nicht mehr direkt: als „OctoPrint"-Host
wird https://<aiopta>/api/v1/addons/octoprint-proxy eingetragen (Orca
hängt /api/... an). Die Endpunkte (api/version, api/files/local,
api/files/local/[name], downloads/files/local/[name] — bewusst
statische Routen, siehe
Runtime-Kompatibilität) validieren den
Orca-X-Api-Key als Aiopta Agent-/User-API-Key (mc_…, via
Core-getAuthUser) und reichen den Request mit HMAC-Grant weiter —
der Grant ist DER Auth-Weg auch auf den OctoPrint-Endpunkten
(/api/version, /api/files/*; write-caps bei POST). proxyApiKey
(X-Api-Key) ist nur noch optionaler Legacy-Fallback für Installationen
ohne grantSecret. Uploads gestreamt (duplex: "half", kein Vollpuffer),
Responses 1:1 im OctoPrint-JSON-Format. Die gemeinsame
Auth/Mapping/Forwarding-Logik liegt zentral in src/lib/orca-api.ts.
- MCP-Server (mcp/servers/proxy-tools/server.mjs, Node-STDIO): vier
Tools, davon drei read-only und eines mutierend.
| Key | Typ | Default | Beschreibung |
| --- | --- | --- | --- |
| baseUrl | text | keiner (Pflicht) | Basis-URL der eigenen Proxy-Instanz im LAN, Form http://<host>:<port> (Beispiel: http://proxy.lan:8000). Leer ⇒ kein Netzruf, sondern „nicht konfiguriert". |
| grantSecret | password (secret) | — | Geteiltes HMAC-Secret; muss mit AIOPTA_GRANT_SECRET des Proxy übereinstimmen. |
| proxyApiKey | password (secret) | — | Statischer Proxy-Key — optional, nur Legacy-Fallback für Installationen ohne grantSecret. |
| pollIntervalSeconds | number | 10 (2–300) | Aktualisierungs-Intervall des Dashboards. |
| allowUsbMirrorDelete | boolean (adminOnly) | false | Erlaubt USB-Sync mit delete=true (zusätzlich confirm=DELETE nötig). |
capabilityDeclarations im Manifest ist der Selbstausweis des Addons nach
dem Addon-Adoption-Standard: je
Eintrag die dotted Capability, ihre Slash-Form (permission) und
die Tier-Stufe. Die Slash-Form ist immer exaktcapability.split('.').join('/') — scripts/check-addon-adoption.cjs
rechnet das nach.
| Capability (dotted) | Permission (slash) | Tier | Deckt |
| --- | --- | --- | --- |
| addons.octoprint-proxy.read | addons/octoprint-proxy/read | elevated | Status (inkl. Kette), Job-Liste, Job-Detail, Versionshistorie, Orca-Listing |
| addons.octoprint-proxy.write | addons/octoprint-proxy/write | elevated | Sammel-Permission der Schreib-Skill (Retry + USB-Sync) |
| addons.octoprint-proxy.job.retry | addons/octoprint-proxy/job/retry | elevated | POST jobs/{id}/retry, auch das einzige schreibende MCP-Tool |
| addons.octoprint-proxy.kette.quittieren | addons/octoprint-proxy/kette/quittieren | elevated | POST kette/abgelehnt/quittieren (räumt abgelehnte Uploads aus der Proxy-Liste) |
| addons.octoprint-proxy.usb.sync | addons/octoprint-proxy/usb/sync | elevated | POST usb/sync (mit delete=true nur über Admin-Setting + confirm=DELETE) |
| addons.octoprint-proxy.file.download | addons/octoprint-proxy/file/download | elevated | Job-Download (Queue oder Git-Fassung), Orca-Download |
| addons.octoprint-proxy.file.upload | addons/octoprint-proxy/file/upload | elevated | POST api/files/local (OrcaSlicer-Upload in die Druck-Queue) |
Warum durchgehend elevated und nicht standard/highest: jeder Aufruf
steuert das vom Betreiber konfigurierte Backend (den LAN-Proxy) — das
ist nach der Tier-Rubrik gebundener Egress, also elevated. Kein Aufruf
führt fremden Code aus, gibt Credentials heraus oder löscht instanzweit;
das USB-Mirror-Delete räumt ausschließlich den addon-eigenen Spiegel
unter /usb/OctoPrint auf. Damit ist highest nicht gerechtfertigt.
Die Durchsetzung für Agent-API-Keys erfolgt core-seitig (Agent-Scope-
Enforcement anhand der deklarierten Permissions); der Grant trägt die
Achse zusätzlich Richtung Proxy (caps: lesend ["read"], mutierend["read","write"]).
Die Trust-/Sandbox-Stufe eines Addons ist kein Manifest-Feld. Sie wird
vom Betreiber pro Addon gesetzt (PATCH /api/v1/admin/extensions mit{ id, trust }), im extensions.settings-Schlüssel trust abgelegt und
in route-dispatch durchgesetzt (src/lib/access/addon-trust.ts im Core).
Der Default ist standard, das Addon braucht dafür keine Zeile Code.
Praktische Folge für dieses Addon: auf restricted werden alle
mutierenden Verben (POST) am Dispatch mit 403 abgewiesen. Retry,
USB-Sync und der OrcaSlicer-Upload fallen damit aus; lesend bleibt
alles erreichbar. Wer OrcaSlicer über dieses Addon drucken lassen will,
braucht also mindestens standard.
attestation.json) — offene LückeDer Adoption-Standard verlangt zusätzlich eine signierteattestation.json, deren declares.capabilities diecapabilityDeclarations spiegelt. Dieses Addon hat sie nicht: signiert
wird ausschließlich im Jenkins-Auftrag ci/Jenkinsfile.addonsign mit der
Credential aiopta-addon-signing-key, die weder im Repo noch bei einem
Entwickler liegt (fail-closed, kein Ersatzweg). Die Lücke ist inscripts/check-addon-adoption.cjs unter addons#1002 ticketgebunden
eingetragen und deckt ausschließlich den Befund
„attestation.json missing" — jeder andere Vertragsverstoß macht den
Flottenlauf weiterhin rot.
| Route | Methode | Proxy-Ziel |
| --- | --- | --- |
| .../status | GET | GET /status (+ pollIntervalSeconds im Envelope) |
| .../jobs | GET | GET /api/proxy/jobs |
| .../jobs/{id} | GET | GET /api/proxy/jobs/{id} (404 passthrough) |
| .../jobs/{id}/versions | GET | GET /api/proxy/jobs/{id}/versions (Git-Historie, 404 passthrough) |
| .../jobs/{id}/download | GET | GET /api/proxy/jobs/{id}/download[?commit=<sha>] (binär gestreamt; 400/404/409 passthrough) |
| .../jobs/{id}/retry | POST | POST /api/proxy/jobs/{id}/retry |
| .../kette/abgelehnt/quittieren | POST | POST /api/proxy/kette/abgelehnt/quittieren (400/409/422 passthrough) |
| .../usb/sync | POST | POST /api/proxy/usb/sync (Delete-Guard s. Settings) |
| .../api/version | GET | GET /api/version (OrcaSlicer) |
| .../api/files/local | GET | GET /api/files/local (Query durchgereicht) |
| .../api/files/local/{name} | GET | GET /api/files/local/<name> (einstufige Namen) |
| .../api/files/local | POST | POST /api/files/local (Multipart-Upload, gestreamt) |
| .../downloads/files/local/{name} | GET | GET /downloads/files/local/<name> (Ziel von refs.download) |
jobs/{id}/download und downloads/files/local/{name} reichen den Body
als Stream durch (kein Vollpuffer, kein apiSuccess-Envelope) und nehmencontent-disposition mit — sonst speicherte der Browser eine Datei mit
Unicode-Namen unter dem letzten Pfadsegment.
Nicht jede Route des Proxy gehört unter die Addon-Basis-URL. Gemessen am
2026-08-10 gegen Proxy-Commit e82e861: der Proxy führt 19
Methode-Pfad-Paare (16 im OpenAPI-Schema, drei ohne — /, /dashboard,/static/*). Die zwölf Manifest-Endpunkte oben decken 13 davon ab
(api/files/local trägt GET und POST); die restlichen sechs bleiben
absichtlich draußen — damit das Manifest nichts verspricht, was es nicht
hält, und nichts verschweigt, was es könnte:
| Proxy-Route | Warum nicht |
| --- | --- |
| GET /healthz, GET /readyz, GET /metrics | Betriebs-Endpunkte des Dienstes. Aiopta hat dafür sein eigenes Modell (container.healthPath, Monitoring-Addon); eine zweite, ungeschützte Kopie hinter der Addon-Auth wäre eine Fehlanzeige statt einer Messung. |
| GET /, GET /dashboard, /static/* | Die eigene Oberfläche des Proxy. In Aiopta ist src/page.tsx die Seite; zwei Oberflächen für dieselben Daten würden auseinanderlaufen. |
Die OrcaSlicer-Endpunkte sind bewusst statische Routen (plus einstufige[name]-Dynamik), keine [[...path]]-Catch-all: der Core-Runtime-Router
(jiti, runtime-installierte ZIPs) resolvt dynamische Verzeichnisse nur mit
einem Segment pro Ebene — eine mehrstufige Catch-all liefert dort 404
(„No handler found"). Das ist ein bekannter Core-Bug, verfolgt als
Aiopta/aiopta-core#1355;
das Addon umgeht ihn konventionsnah statt auf den Fix zu warten.
Konsequenzen:
\n- api/version, api/files/local (GET+POST) und
api/files/local/[name] (GET) funktionieren in BEIDEN Welten
(runtime-installiertes ZIP und gebündelter Next.js-Weg). Params kommen
runtime-seitig als Record mit Bracket-Key — routeParam in
src/lib/orca-api.ts akzeptiert beide Formen.
- Verschachtelte Datei-Detail-Pfade (files/local/<ordner>/<datei>)
sind runtime-seitig bis zum Core-Fix #1355 nicht erreichbar (404);
einstufige Namen decken den OrcaSlicer-Hauptweg ab. Der gebündelte Weg
(Zielweg nach Core-Repair
Aiopta/aiopta-core#1356)
kann tiefe Pfade nachziehen, sobald der Router sie in beiden Welten
kann.
proxy-tools)| Tool | Wirkung |
| --- | --- |
| proxy_status | GET /status — vier Teilstati inkl. G-Code-Kette (read-only) |
| proxy_list_jobs | GET /api/proxy/jobs — inkl. Kettenstand je Job (read-only) |
| proxy_job_detail | GET /api/proxy/jobs/{id} — inkl. vollem Kettenbericht (read-only) |
| proxy_retry_job | MUTIEREND: POST /api/proxy/jobs/{id}/retry — einziges schreibendes Tool |
Der Server minted den Grant selbst (gleiche Implementierung wiesrc/lib/grant.ts). Die deklarierten Slots (configRefs: ["baseUrl"],credentialRefs: ["grantSecret", "proxyApiKey"]) werden core-seitig
aufgelöst und als AIOPTA_CONFIG_BASEURL /AIOPTA_CREDENTIAL_GRANTSECRET / AIOPTA_CREDENTIAL_PROXYAPIKEY
injiziert. Ohne aufgelöste Credentials schlägt jeder Tool-Call sauber
fehl („nicht konfiguriert") — Handshake und tools/list funktionieren
immer.
- Der Sync Proxy läuft im eigenen LAN; seine Adresse trägt der Betreiber
in baseUrl ein (kein öffentlicher Zugriff nötig/möglich). Es gibt
keinen Vorgabewert — ohne Eintrag arbeitet das Addon nicht und sagt
das auch, statt eine Adresse zu raten.
- AIOPTA_GRANT_SECRET auf der Proxy-Seite == grantSecret hier — der
Grant wird auf /api/proxy/* UND den OctoPrint-Endpunkten (/api/*)
akzeptiert und ist der empfohlene Weg.
- PROXY_API_KEY / proxyApiKey: optionaler Legacy-Fallback, wenn kein
grantSecret gesetzt ist. Ohne beides antwortet das Addon mit
„grantSecret nicht konfiguriert".
- OrcaSlicer: Host https://<aiopta>/api/v1/addons/octoprint-proxy,
API-Key = Aiopta Agent-API-Key (mc_…) mit Scope
addons/octoprint-proxy/*.
Das Manifest deklariert weder addonDependencies noch requires — und
das ist eine Entscheidung, keine Auslassung. Eine required-Kante auf ein
Addon, das auf der Instanz nicht installiert oder deaktiviert ist, lässt
Installation und Aktivieren nach ADR-047 mit 409
(addon_dependencies_unmet) scheitern
(src/lib/addons/dependency-check.ts im Core).
Geprüft und bewusst NICHT verdrahtet:
\n| Kandidat | Befund |
| --- | --- |
| octoprint | Existiert als eigenes Addon, spricht aber direkt mit einer OctoPrint-Instanz. Dieses Addon spricht mit dem Sync Proxy. Keine Aufrufbeziehung, also keine Kante. |
| spoolman | Gibt es zum Prüfzeitpunkt (2026-08-10) nicht — addons/spoolman entsteht gerade unter addons#1126. Eine Kante darauf wäre heute ein garantierter 409. |
| mount-manager | Existiert nicht; Epic #881 (siehe unten). |
Namensfallen für die nächste Prüfung: „Git" heißt hier forgejo,
„WooCommerce" steckt in wordpress, „n8n" heißt workflow-builder. Wer
eine Kante ergänzt, prüft den Verzeichnisnamen unter addons/, nicht
den Produktnamen.
Die USB-Mount-Verwaltung liegt aktuell außerhalb von Aiopta (fstab/udev auf
dem Proxy-Host, manuell eingerichtet). Sobald das Epic
#881
(mount-manager — zentrale Verwaltung von Block-Devices, fstab/udev,
UI mit Permissions, Freigabe von Mounts an Addons/Agenten) umgesetzt ist,
wird dieses Addon mount-manager als addonDependency deklarieren und den
USB-Pfad aus dessen Freigabe-Modell beziehen. Bis dahin bleibt die
host-seitige Einrichtung wie im Proxy-Repo dokumentiert
(docs/PROXMOX-USB-PASSTHROUGH.md, docs/USB-SETUP.md).
Generate 3D-printable OpenSCAD models from text prompts and images, render previews, and export
STL — all from inside Aiopta.
- Text to OpenSCAD: Describe your model in natural language. Generation is an LLM task and
runs through the Aiopta LLM gateway (@/lib/gateway) — never a hard-coded model host
(ADR-009). A deterministic keyword-based generator is used as an offline fallback when no model
is reachable.
- Image to OpenSCAD: Convert 2D images to extruded 3D models (via Trace2SCAD or OpenCV
contours, server-side).
- Preview Rendering & STL Export: The openscad binary is an external tool, so it runs in
the addon's render container (declared in the manifest container block). The render route
reaches it via Aiopta's internal container URL; a local openscad CLI is used as a dev
fallback.
- LLM via gateway only. text-to-openscad.ts calls chatCompletionWithFallbacks from
@/lib/gateway; it does not talk to Ollama or any model endpoint directly.
- External tool as a container. The OpenSCAD renderer is declared as a container in
addon.json / manifest.ts (registry.langkau.info/aiopta/openscad-render). It is
booted at install by the container-service, started/stopped by enable/disable (G6 lifecycle),
and reached only via getContainerAddonInternalUrl("openscad-generator").
- No secrets in the manifest. The render image is stateless (envSchema: []); any future
secret must go through envSchema + Aiopta config.
All routes are namespaced under /api/v1/addons/openscad-generator/ and require auth.
### Generate (text or image → OpenSCAD)
```
POST /api/v1/addons/openscad-generator/generate
{ "type": "text", "input": "I need a watering can" }
{ "type": "image", "input": "/tmp/source.png", "options": { "height": 5, "layers": 10 } }
```
### Render / export (OpenSCAD code → PNG preview or STL)
```
POST /api/v1/addons/openscad-generator/render
{ "format": "png", "code": "<openscad code>", "options": { "width": 800, "height": 600 } }
{ "format": "stl", "code": "<openscad code>" }
```
The response includes source ("container" or "cli") and, for the container path, a base64dataBase64 payload.
### Status
```
GET /api/v1/addons/openscad-generator/status
→ { ok, capabilities, textGeneration: "gateway", renderContainerAvailable }
```
The render image is expected to expose:
\n- POST /render — body { code, format: "png"|"stl", width?, height? }, returns
{ dataBase64 } (base64 PNG or STL).
- GET /api/v1/health — health probe used by the container-service.
\nTODO(owner):
openscad-render-image— building and publishing the
registry.langkau.info/aiopta/openscad-renderimage is owner-run (registry currentlyin outage). Until it is published, render falls back to a local
openscadCLI in dev. See
docs/OPEN-DECISIONS.md.
addons/openscad-generator/\n├── addon.json # Manifest (page + container + endpoints)\n├── README.md\n├── SKILL.md # Agent skill\n├── src/\n│ ├── manifest.ts # Extension (dual-registration: routes + page + container)\n│ ├── page.tsx # Addon UI (registered page)\n│ ├── text-to-openscad.ts # Text→SCAD via @/lib/gateway (+ offline fallback)\n│ ├── image-to-openscad.ts # Image→SCAD via Trace2SCAD/contours\n│ ├── render-openscad.ts # Render PNG + export STL (container-first, CLI fallback)\n│ └── app/api/v1/addons/openscad-generator/{generate,render,status}/route.ts\n└── tests/unit/ # manifest validity + gateway-backed generation (gateway mocked)MIT
", "byteSize": 3839 } } }, { "id": "paid-sample", "uuid": "7cc803ea-f53f-4dd4-b12a-b77b576c6961", "name": "Pro Pack (Paid-Addon Sample)", "version": "1.0.2", "description": "Beispiel-Addon für kostenpflichtige Marketplace-Eintraege (issue #89). Demonstriert das neue `pricing`-Feld in addon.json + Catalog: nur nach Registrierung + Login + 'Kaufen' + Mock-Payment downloadbar. Hat selbst keinen UI-Surface — der Wert liegt im演示ieren der Bezahl-Flow.", "author": "Aiopta", "icon": "💎", "capabilities": [ "paid-listing-sample" ], "tags": [], "download": "/api/v1/store/download?addon=paid-sample", "sha256": "9eab35d0fc74aad56dbc14562ee5739510abc4b57610878ec2bb46515489cbb4", "size": 2784, "page": null, "deprecated": false, "endpoints": [], "skills": [ { "name": "paid-sample-info", "displayName": "Pro Pack (Paid Sample): Info", "description": "Liest die Pricing-Metadaten dieses Addons und gibt sie zurück. Kostet nichts aufzurufen — der Kauf ist eine演示 des Paywalls, nicht ein API-Gate für die Info selbst.", "permissions": [ "addons/paid-sample/status" ], "endpoint": "/api/v1/addons/paid-sample/status", "scripts": [] } ], "mcpServers": [], "pricing": { "amount": 499, "currency": "EUR", "kind": "one-time" }, "pricingTiers": { "schemaVersion": 1, "currency": "EUR", "tiers": [ { "id": "standard", "name": "Standard", "priceMinor": 499, "interval": "one_time", "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "Demonstrations-Addon für kostenpflichtige Marketplace-Eintraege. Der
eigentliche Wert liegt nicht in irgendwelchen Features, sondern darin,
den kompletten Auth + Paywall + Download-Flow einmal real durch den
Store zu schicken:
1. Im Store-Browse als 💎 Pro Pack sichtbar mit Preis-Tag 4,99 €.
2. Beim Klick auf "Kaufen" oeffnet sich der Login/Register-Modal
(User-Story: Store-Betreiber moechte, dass kostenpflichtige Addons
nur nach Registrierung + Login + Kauf heruntergeladen werden
koennen).
3. Nach Registrierung + Klick auf "Kaufen" erstellt das Backend einen
Checkout (Mock-Stripe-Signatur, status=pending) und das SPA ruft
/api/v1/store/payment/simulate mit status=success auf.
4. Sobald die Purchase auf paid steht, schaltet der Download-Button
scharf. Das Artifact wird vom Backend mit
Content-Disposition: attachment gestreamt.
Dieses Addon hat bewusst keine src/-UI — der UI-Surface waere nur
Rauschen. Das Manifest selbst ist die Demonstration.
pricing.amount: 499 (Cents, nicht Euro — Integer, ADR-konform)pricing.currency: EUR (ISO 4217, Whitelist: EUR/USD/GBP/CHF)pricing.kind: one-time (vs. subscription)Aenderungen an pricing.amount <= 0 oder fehlendes pricing-Feld
bedeuten automatisch "free" — dann erscheint der Eintrag im Store
ohne Preis-Tag und der Download ist weiterhin oeffentlich via nginx.
Rechnungen (Invoices), Abos (Subscriptions), Payment-Links und Mahnwesen (Dunning) über Stripe + PayPal
— providerseitig konfigurierbar und auch für Aioptas eigene Abrechnung (Phase Q) nutzbar.
Foundation-Addon für spätere accounting / membership / marketing-ads.
\nMoney-Stufe-1 · ADR-039 · Connector-Pattern (Stripe/PayPal sind SaaS — kein Container).
- Rechnungen — anlegen/listen/lesen/senden/als-bezahlt-markieren/stornieren. Positionen, Währung,
USt; Statusmaschine draft → open → paid | void | uncollectible. Lokale SQLite ist die Quelle der
Wahrheit; der Provider hostet die Rechnung / erzeugt die Zahl-URL.
- Abos — anlegen/listen/kündigen gegen eine vom Owner bereitgestellte Price-/Plan-ID; Status
active | past_due | canceled.
- Payment-Links — teilbare Zahl-URL für einen Einmalbetrag; listen/deaktivieren.
- Mahnwesen — Eskalationsstufen (1–3) + zuletzt-versendet für überfällige Rechnungen; Versand über die
Notifications (falls installiert), sonst wird der Zustand nur erfasst und angezeigt.
- Webhooks — POST /webhooks/{provider} empfängt Stripe/PayPal-Events, verifiziert die Signatur
und aktualisiert lokalen Status idempotent.
- Aiopta-Billing-Tie-in — ein dünner interner Helper (src/lib/aiopta-billing.ts), damit Aiopta instances Phase-Q-Metering
eine Rechnung/ein Abo über dieses Addon ausstellen kann — ohne Metering zu duplizieren (liest
@/lib/quotas), und einen bezahlten Tarif über dieselbe Naht wie der Invite-Pfad
(applyInviteAssignment) setzen kann.
Beide Provider sind optional — ohne Keys läuft das Addon graceful im Lesemodus (kein Geld ohne
Owner-Keys). Secrets liegen ausschließlich in Aiopta addon-config (addon.config.payments.*, is_secret=1);
der einzige Echo ist ein maskierter set(len=…)-Hinweis.
| Schlüssel | Provider | Zweck |
|-----------|----------|-------|
| STRIPE_SECRET_KEY | Stripe | API-Key (Bearer) |
| STRIPE_WEBHOOK_SECRET | Stripe | Webhook-HMAC-Secret (Stripe-Signature) |
| STRIPE_MODE | Stripe | test \\| live |
| PAYPAL_CLIENT_ID / PAYPAL_CLIENT_SECRET | PayPal | OAuth2 Client-Credentials |
| PAYPAL_WEBHOOK_ID | PayPal | Webhook-ID für die verify-API |
| PAYPAL_MODE | PayPal | sandbox (Default) \\| live |
Konkrete Keys/Webhook-Secrets, live-vs-test und die Price-/Plan-IDs sind Owner-Entscheidungen — siehedocs/OPEN-DECISIONS.md (billing-payment-provider / payments-stripe, payments-paypal,payments-price-ids).
- Secrets nur via Aiopta-Config, nie geloggt, nur maskiert echo'd (maskSecret).
- Webhook-Signaturprüfung ist Pflicht: Stripe HMAC-SHA256 über den Rohbody (Stripe-Signature,
Replay-Toleranz 5 min, konstantzeitiger Vergleich); PayPal über die verify-webhook-signature-API gegen
die konfigurierte PAYPAL_WEBHOOK_ID. Fehlende/ungültige Signatur → 400, keine State-Mutation.
Webhook-Events sind über markWebhookSeen idempotent.
- Geldbewegende Routen sind POST/PUT/DELETE mit mc-session-Auth und erfordern einen konfigurierten
Provider (sonst 400 — kein stilles No-Op). GET/Daten-Routen degradieren graceful (200, leere/configured:false).
- Idempotency bei jedem Provider-Create (Stripe Idempotency-Key, PayPal PayPal-Request-Id).
- Validierung: Betrag > 0 (Minor-Units), Währungs-Whitelist (EUR/USD/GBP/CHF/CAD/AUD), USt 0–100.
Kein PII in Logs/URLs (Kunden-E-Mail wird in der Mahnliste maskiert).
addons/payments/\n addon.json # Manifest (Endpoints, Page, Widget, Skills; kein Container)\n src/manifest.ts # Dual-Registration (ADR-001), String-Literal route()-Handler\n src/page.tsx # PaymentsPage (Tabs: Rechnungen/Abos/Links/Mahnwesen + Provider-Panel)\n src/widget.tsx # Dashboard-Widget (key-values, graceful)\n src/lib/\n money.ts # pure: Währungs-Whitelist, Beträge, Summen, Formatierung\n errors.ts # PaymentsError (+ HTTP-Status)\n provider-config.ts # liest Provider-Secrets aus Aiopta-Config, maskierte Hints\n providers/types.ts # PaymentProvider-Interface (wie BackendDriver) + Money/LineItem\n providers/stripe.ts # Stripe (raw REST, HMAC-Webhook-Verify) — vollständig\n providers/paypal.ts # PayPal (OAuth2 REST, verify-API) — gleiche Schnittstelle\n providers/index.ts # Registry/Factory: resolveWriteProvider, defaultProvider\n payments-store.ts # SQLite-Quelle-der-Wahrheit + Statusmaschinen (pure + DB)\n dunning.ts # Mahnlauf, Reminder-Versand (Notifications-Reuse, graceful)\n status.ts # /status-Aggregat (Provider + Summary), graceful\n aiopta-billing.ts # Phase-Q-Tie-in (Rechnung/Abo ausstellen, Tarif-Naht)\n src/app/api/v1/addons/payments/**/route.ts # thin Handler (apiSuccess/apiError)\n tests/unit/ # money, store (Statusmaschine+DB), providers (Signatur), manifest, routes-graceful\n SKILL.md, README.mdnpx vitest run addons/payments- money.test.ts — pure Validierung/Math.
- payments-store.test.ts — Statusmaschine (pure) + DB (In-Memory SQLite): Transitions, Abos,
Payment-Links, Mahn-Cap, Webhook-Idempotenz + applyWebhook.
- providers.test.ts — Stripe-Signaturprüfung (gültig/manipuliert/abgelaufen), Klassifizierer,
Happy-Path (mock fetch) + not-configured-Refusal, Registry.
- manifest.test.ts — Manifest gültig, namespaced, kein Container, keine Secrets/Hosts.
- routes-graceful.test.ts — Daten-Routen 200/leer ohne Provider; Webhook lehnt unkonfiguriert/unbekannt ab.
Prediction market addon with market discovery, positions, open orders, and direct order placement via the official Polymarket CLOB client.
\npolymarket/addons/polymarketKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\nnpm-Abhängigkeiten (werden bei Installation aufgelöst): @polymarket/clob-client-v2, viem.
| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/polymarket |
| GET | /api/v1/addons/polymarket/book |
| GET, POST, DELETE | /api/v1/addons/polymarket/config |
| GET | /api/v1/addons/polymarket/markets |
| GET, POST, DELETE | /api/v1/addons/polymarket/orders |
| GET | /api/v1/addons/polymarket/positions |
| GET | /api/v1/addons/polymarket/status |
", "byteSize": 1134 } } }, { "id": "proxmox", "uuid": "13e9fe70-e0df-4254-9de4-295e89b75d1c", "name": "Proxmox VE", "version": "1.0.5", "description": "Control Proxmox VE — start/stop/shutdown/reboot VMs and LXC containers, node overview and cluster resources via the Proxmox API.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "node-overview", "vm-control", "lxc-control", "cluster-resources", "connection-config" ], "tags": [], "download": "/artifacts/proxmox-1.0.5.zip", "sha256": "ba1324d0094fffcb7a7c769435fb2bb2b54d1baac3a20878f98eae5163e2c097", "size": 110029, "page": { "id": "proxmox-page", "path": "/addons/proxmox", "name": "Proxmox VE", "icon": "🖥️", "section": "Tools", "component": "@addons/proxmox/src/components/ProxmoxPage" }, "deprecated": false, "endpoints": [ "/api/v1/addons/proxmox/status", "/api/v1/addons/proxmox/nodes", "/api/v1/addons/proxmox/resources", "/api/v1/addons/proxmox/nodes/:node/qemu", "/api/v1/addons/proxmox/nodes/:node/qemu/:vmid/status", "/api/v1/addons/proxmox/nodes/:node/qemu/:vmid/start", "/api/v1/addons/proxmox/nodes/:node/qemu/:vmid/stop", "/api/v1/addons/proxmox/nodes/:node/qemu/:vmid/shutdown", "/api/v1/addons/proxmox/nodes/:node/qemu/:vmid/reboot", "/api/v1/addons/proxmox/nodes/:node/lxc", "/api/v1/addons/proxmox/nodes/:node/lxc/:vmid/status", "/api/v1/addons/proxmox/nodes/:node/lxc/:vmid/start", "/api/v1/addons/proxmox/nodes/:node/lxc/:vmid/stop", "/api/v1/addons/proxmox/nodes/:node/lxc/:vmid/shutdown", "/api/v1/addons/proxmox/nodes/:node/lxc/:vmid/reboot", "/api/v1/addons/proxmox/config", "/api/v1/addons/proxmox/test" ], "skills": [], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Control a Proxmox VE cluster from Aiopta:
node overview, cluster-wide VM/LXC list, per-guest status, and power actions
(start / shutdown / stop / reboot) — via the Proxmox API token.
- Node overview — list cluster nodes and their state.
- Cluster resources — all QEMU VMs and LXC containers in one call (/resources).
- Guest control — start, clean-shutdown, hard-stop, reboot for VMs and containers.
- Connection config — host/port + API token stored on the server; the token
secret is never returned to the client.
- Dashboard widget proxmox.status — running vs. total guests.
- Agent skill (SKILL.md) — token-sparing single-REST-call control for agents.
1. Create an API token in Proxmox (Datacenter → Permissions → API Tokens):
- Pick a user/realm (e.g. root@pam) and a token id (e.g. mc).
- Give the token the permissions it needs (e.g. PVEVMAdmin on / or per-VM).
- Copy the secret — Proxmox shows it once.
- The full token id is USER@REALM!TOKENID (e.g. root@pam!mc).
2. Configure in Aiopta (Proxmox addon → Settings, or PUT /config):
- host (e.g. pve.example.com), port (default 8006),
- tokenId (root@pam!mc), tokenSecret,
- verifyTls — uncheck if your Proxmox uses the default self-signed cert.
3. Test the connection (Test button, or POST /test).
Proxmox ships a self-signed certificate by default. Set verifyTls: false
to connect anyway (the client then disables certificate verification for the
Proxmox host only). Use a proper certificate + verifyTls: true in production.
Base: /api/v1/addons/proxmox
| Method | Path | Description |
|--------|------|-------------|
| GET | /status | Reachability + Proxmox version |
| GET | /nodes | Cluster node list |
| GET | /resources | All VMs + LXC (vmid, node, type, status, name) |
| GET | /nodes/{node}/qemu | VMs on a node |
| GET | /nodes/{node}/qemu/{vmid}/status | VM status |
| POST | /nodes/{node}/qemu/{vmid}/start | Start VM |
| POST | /nodes/{node}/qemu/{vmid}/shutdown | Clean shutdown |
| POST | /nodes/{node}/qemu/{vmid}/stop | Hard power-off |
| POST | /nodes/{node}/qemu/{vmid}/reboot | Reboot |
| GET | /nodes/{node}/lxc | Containers on a node |
| GET | /nodes/{node}/lxc/{vmid}/status | Container status |
| POST | /nodes/{node}/lxc/{vmid}/start\\|shutdown\\|stop\\|reboot | Container power actions |
| GET | /config | Current config (token secret masked) |
| PUT | /config | Set connection + token (auth-gated) |
| POST | /test | Test the configured connection (auth-gated) |
shutdown is a clean shutdown (guest agent / ACPI); stop is a hard power-off.
Control routes (POST) and PUT /config run under the per-agent key scoping from
Phase S — proxmox/* is its own capability.
src/\n├── lib/\n│ ├── config.ts # data/proxmox-config.json (load/save/mask)\n│ ├── client.ts # Proxmox API client (PVEAPIToken auth, TLS opt-out, timeouts)\n│ ├── types.ts # ProxmoxConfig, PveNode, PveResource, PveGuestStatus, …\n│ └── response.ts # { success, data } envelope helpers\n├── manifest.ts # Extension + route registration\n├── page.ts # Sidebar page (section "Tools")\n├── components/ProxmoxPage.tsx\n└── app/api/v1/addons/proxmox/... # route handlersRetrieval-Augmented Generation: a standalone semantic-search addon that chunks,
embeds, stores and retrieves documents over a self-hosted Qdrant sidecar. Other
addons (memories, knowledge-base) detect this capability at runtime viaisAddonAvailable("rag") and use it optionally — falling back to their own
(SQL LIKE) search when RAG is not installed or the Qdrant sidecar is absent.
This README covers the addon surface (Issue #587, Slice 1). The pipeline
itself lives in the core library src/lib/rag/ (seedocs/rag.md in aiopta-core); this addon only consumes
that library.
- Addon-ID: rag
- Version: 1.7.0
- Fähigkeiten (capabilities): rag, knowledge-management
- UI-Seite: /addons/rag (RAG-Konsole: Status, Ingest, Search)
- Abhängigkeiten: keine (standalone). Optionaler Qdrant-Sidecar
(docker compose up -d qdrant).
Seit dem Knowledge-Epic (core#816, Slice 2 core#818) ist RAG Anbieter 1
(kind: "vector") der generischen knowledge-management-Fähigkeit: DerRagService wird über src/lib/knowledge-adapter.ts auf den VertragKnowledgeManagementCapability aus @aiopta/sdk abgebildet und insrc/lib/capability-register.ts unter core.knowledge.management
registriert (Provider-Liste der Core-Registry, registerCapabilityProvider).
Verbraucher codieren gegen die Fähigkeit, nie gegen dieses Addon; welcher
Anbieter für wen aktiv ist, entscheiden Resolver + Zustimmung (core#820/#821).
Wichtig: Wissen ≠ Gedächtnis (Owner-Entscheidung 2026-08-03) — was der Agent
über den Nutzer behält, bleibt allein im memories-Addon.
RAG ist ein eigenständiges Addon — kein direkter Einbau in memories. Das
Pattern ist Capability-Detection:
import { isAddonAvailable } from "@/lib/addons/availability";if (await isAddonAvailable("rag")) {
// use src/lib/rag vector search (chunk + embed + retrieve, Qdrant)
} else {
// existing SQL LIKE search (fallback, no regression)
// + store-link in the UI: "Install the RAG addon for semantic search"
}
```
- NICHT addonDependencies (hard deps) — RAG ist optional, kein 409-Block.
- isAddonAvailable("rag") (availability.ts:154) ist die kanonische
Prüfung. Keine neue hasCapability erfinden.
- Registry: addonRegistry.getByCapability("rag") findet dieses Addon.
src/lib/rag/)document text ──► chunk (rag/chunk.ts)\n ──► embed (rag/embedding.ts) ← injectable provider\n ──► store (rag/vector-store.ts) ← Qdrant sidecar, degrades gracefully\nquery text ──► embed ──► search (store) ──► rank (rag/retrieve.ts)| Stage | Core module | Notes |
|---|---|---|
| Chunking | rag/chunk.ts | Greedy word packing with overlap, exact char offsets. |
| Embedding | rag/embedding.ts | Injectable EmbeddingProvider; deterministic hash fallback (network-free) for tests/CI. |
| Store | rag/vector-store.ts | QdrantVectorStore over the REST API. Never throws on connectivity. |
| Retrieve | rag/retrieve.ts | Pure cosine ranking + merge/dedupe. |
Das Addon crasht nie, weil der optionale Qdrant-Sidecar fehlt:
\n- createVectorStore() liefert null, wenn RAG_VECTOR_STORE_ENABLED=false.
- Jede QdrantVectorStore-Methode fängt Connectivity-Fehler ab, loggt eine
Warnung und resolve zu einem No-op / leeren Ergebnis. store.available
reflektiert den letzten Kontakt.
- Der deterministische Embedding-Fallback braucht kein Netzwerk/keinen API-Key,
sodass die volle Pipeline (chunk → embed → rank) in CI ohne Container läuft.
- GET /status meldet storeAvailable:false — die UI rendert einen klaren
"nicht bereit"-Zustand, kein Crash.
Jeder Vektor-Punkt trägt ein user_id-Payload-Feld (vom Server aus der Session
gestanzt, niemals ein Client-Wert). Die Suche filtert standardmäßig aufuser_id = <caller> — User A sieht niemals User B's Dokumente. DerincludeOthers-Parameter (Admin-Affordanz) lockert den Filter bewusst.
| Methode | Pfad | Beschreibung |
|---|---|---|
| GET | /api/v1/addons/rag | Addon-Deskriptor (id, capabilities, endpoints). |
| GET | /api/v1/addons/rag/status | Pipeline-Health + Konfiguration (Provider, Dimensions, Qdrant-Verfügbarkeit). Wirft nie. |
| POST | /api/v1/addons/rag/ingest | Dokument chunken + embedden + speichern. user_id vom Server gestanzt. Degradiert zu stored:false, wenn Qdrant nicht erreichbar. |
| POST | /api/v1/addons/rag/ingest/file | Multipart-Datei-Ingestion (#729): PDF/Office/Scan/Text → OCR-zu-Markdown-Konvertierung → dieselbe chunk+embed+store-Pipeline. 400 bei unsupported/oversize, 409 code:"unconfigured" wenn der benötigte Konverter fehlt (nie 5xx). |
| POST | /api/v1/addons/rag/search | Semantische Suche, gescoped auf den Caller (user_id-Payload-Filter). Leeres Resultat (kein Fehler), wenn der Store nicht verfügbar ist. |
| GET | /api/v1/addons/rag/documents | Distinct ingested document ids des Callers (read-only). |
| DELETE | /api/v1/addons/rag/documents/{id} | Löscht ein Dokument + alle seine Chunks (idempotent, gescoped). |
# Ingest a document\ncurl -s -X POST -H "Authorization: Bearer $AIOPTA_API_KEY" -H "Content-Type: application/json" \\\n -d '{"id":"readme-v1","text":"The quick brown fox jumps over the lazy dog."}' \\\n https://<instance>/api/v1/addons/rag/ingest# Semantic search
curl -s -X POST -H "Authorization: Bearer $AIOPTA_API_KEY" -H "Content-Type: application/json" \\
-d '{"query":"quick fox","topK":5}' \\
https://<instance>/api/v1/addons/rag/search
```
Responses use { success, data | error }.
Praxis-Dokumente liegen selten als sauberer Text vor. Am Anfang der
Indexierungs-Pipeline steht deshalb ein Konvertierungs-Schritt, der **jede
Datei in normalisiertes Markdown umwandelt — es wird immer bereinigtes
Markdown in den Wissensspeicher geladen, nie rohe PDFs. Erst nach** der
Markdown-Normalisierung wird gechunkt und embedded (dieselbe Pipeline wiePOST /ingest — keine Parallel-Pipeline).
Konverter-Provider (src/lib/markdown-converter.ts):
| Provider | Pfad | Kann | Kann NICHT |
|---|---|---|---|
| local-text (Default) | lokal, kein Datenabfluss | Text/Markdown-Passthrough; Text-PDFs via pdftotext (poppler, falls installiert) bzw. eingebauter Extraktor für einfache/unkomprimierte PDFs | Scans/Bild-PDFs, Bilder, Office (dokumentierte Grenze — dafür ist OCR nötig) |
| mistral-ocr (optional) | Cloud — Inhalt verlässt die Instanz | Scans, Bilder, Layout-PDFs, Office-Dokumente → strukturiertes Markdown | läuft nur mit konfiguriertem API-Key |
DSGVO / Datenabfluss (Betriebs-Hinweis): Der lokale Pfad ist der Default
und verlässt die Instanz nie. Cloud-OCR (mistral-ocr) wird nur genutzt,
wenn (a) ein Key konfiguriert ist und (b) der lokale Konverter den Inhalt
nicht extrahieren kann (Scan/Bild/Office). Jede Nutzung ist gekennzeichnet:GET /status meldet pro Provider cloud: true/false, die Antwort vonPOST /ingest/file trägt ein cloud-Flag und die RAG-Konsole zeigt den
Egress-Marker ("content leaves this instance") an. Betreiber, die keinen
Datenabfluss wollen, konfigurieren schlicht keinen RAG_MISTRAL_OCR_API_KEY
— Scan-Uploads antworten dann sauber mit 409 code:"unconfigured" (#515),
nie mit einem 5xx.
Persistierte Markdown-Quelle / Reindex ohne OCR: Das normalisierte
Markdown wird pro (user_id, document_id) in der Tabellerag_markdown_sources gespeichert (user-scoped, ADR-054). Re-Chunking/
Reindex (reindexDocument() in src/lib/file-ingest.ts) liest diese Quelle
und läuft ohne erneutes OCR. Re-Ingest derselben Dokument-Id ersetzt
Chunks und Markdown-Quelle vollständig (id-stabil, kein
Duplikat-Wachstum).
Konfiguration:
\nRAG_INGEST_FILE_MAX_BYTES=20971520 # Upload-Limit (Default 20 MiB)\nRAG_MISTRAL_OCR_API_KEY=<key> # aktiviert mistral-ocr (Fallback: MISTRAL_API_KEY)\nRAG_MISTRAL_OCR_BASE_URL=https://api.mistral.ai\nRAG_MISTRAL_OCR_MODEL=mistral-ocr-latest\n# Optional fuer bessere lokale Text-PDF-Extraktion: poppler-utils installieren\n# (apt-get install poppler-utils) — ohne poppler greift der eingebaute\n# Extraktor fuer einfache PDFs; komprimierte Text-PDFs brauchen dann OCR.# Start the sidecar\ndocker compose up -d qdrant# Smoke-check
curl -s http://localhost:6333/readyz
# Defaults already match; override only if needed
# RAG_VECTOR_STORE_URL=http://qdrant:6333 # inside the compose network
# RAG_VECTOR_STORE_ENABLED=false # disable RAG entirely
```
Env vars: RAG_VECTOR_STORE_URL, RAG_VECTOR_STORE_API_KEY,RAG_VECTOR_STORE_ENABLED, RAG_EMBEDDING_PROVIDER,RAG_EMBEDDING_DIMENSIONS. Siehe aiopta-core .env.example + docs/rag.md.
- Slice 1 (dieser PR): Standalone Addon-Surface + Manifest. Konsumiert
src/lib/rag/ + Qdrant-Sidecar. Keine Consumer-Integration.
- Slice 2 (Folge-Issue): memories-Integration (searchMemories()
Vektor-Search-Fallback + Isolation + Store-Link).
- Slice 3 (Folge-Issue): MCP-Server für RAG (rag-tools, read-only search)
+ realer Embedding-Provider (OpenAI/Ollama).
Tracks investment property leads from IMAP and external market sources, calculates deal metrics, and ranks opportunities by configurable scoring.
\nreal-estate-investor/addons/real-estate-investorKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/real-estate-investor/candidates |
| POST | /api/v1/addons/real-estate-investor/candidates/[id]/promote |
| GET, POST | /api/v1/addons/real-estate-investor/config |
| GET, POST | /api/v1/addons/real-estate-investor/objects |
| GET, PUT | /api/v1/addons/real-estate-investor/objects/[id] |
| GET, POST | /api/v1/addons/real-estate-investor/regions |
| GET, POST | /api/v1/addons/real-estate-investor/sources |
| GET | /api/v1/addons/real-estate-investor/status |
| POST | /api/v1/addons/real-estate-investor/sync/mail |
| POST | /api/v1/addons/real-estate-investor/sync/market |
enabled: false).", "byteSize": 1407 } } }, { "id": "revenue-cat", "uuid": "41e76065-d882-4591-b1c6-51d51cf47553", "name": "Revenue Cat (Subscription-Management + Entitlements)", "version": "1.0.2", "description": "Subscription-Management über Revenue Cat — per-user BYOK (eigenes API-Projekt + Secret-API-Key via scopedStore(userId), ADR-054). Holt aktive Subscriptions, Entitlements, Customer-Info und Offerings von Revenue Cats REST API (fetch, kein SDK) und brückt Revenue-Cat-Entitlements ins Core-Entitlement-System (hasEntitlement, core#583). Ein read-only MCP-Server (revenue-cat-tools) exponiert die Daten für Agenten (#384). Ohne konfigurierten API-Key läuft das Addon graceful im Lesemodus — KEIN Default/Anonymous-Zugriff (INBOX-86-Analogie). Keys werden NIE geloggt. Money-Stufe-1 (ADR-039).", "author": "Aiopta", "icon": "🧩", "capabilities": [ "subscriptions", "entitlements", "customers", "offerings" ], "tags": [], "download": "/artifacts/revenue-cat-1.0.2.zip", "sha256": "fedfcb462ad452a128babc88a77435bbaedd50647a81568aa6563068e40b03e7", "size": 99685, "page": { "id": "revenue-cat-page", "path": "/addons/revenue-cat", "name": "Revenue Cat", "icon": "🐱", "section": "Money", "component": "@addons/revenue-cat/src/page" }, "deprecated": false, "endpoints": [ "/api/v1/addons/revenue-cat/status", "/api/v1/addons/revenue-cat/config", "/api/v1/addons/revenue-cat/subscriptions", "/api/v1/addons/revenue-cat/entitlements", "/api/v1/addons/revenue-cat/customer", "/api/v1/addons/revenue-cat/offerings", "/api/v1/addons/revenue-cat/widget" ], "skills": [], "mcpServers": [ { "id": "revenue-cat-tools", "displayName": "Revenue Cat tools", "description": "Read-only Revenue Cat companion tools for agents: normalize/filter active subscriptions, project a customer's entitlements, summarize the customer info (active subs + non-subscription purchases) and project an offerings/package tree — faithful ports of the revenue-cat addon's src/lib projection helpers (issue #545, epic #399). Mutates nothing; live per-user Revenue Cat access is resolved core-side via the declared config/credential slots.", "transport": "stdio", "runtime": "node", "entry": "revenue-cat-tools/server.mjs", "permissions": [ "addons/revenue-cat/read" ], "toolPolicy": { "mode": "read-only", "allowDestructive": false }, "configRefs": [ "projectId" ], "credentialRefs": [ "apiKey" ], "archiveEntry": "revenue-cat/mcp/servers/revenue-cat-tools/server.mjs", "sha256": "f5f50508a918f474995661bab9f6f54c9cd5ee1f8397445d59ebe554133f3eea", "size": 19924, "descriptorVersion": 1 } ], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Subscription-Management über Revenue Cat — per-user
BYOK (Bring-Your-Own-Key), an Aiopta angebunden. Holt aktive Subscriptions,
Entitlements, Customer-Info und Offerings von Revenue Cats REST API und brückt
Revenue-Cat-Entitlements ins Core-Entitlement-System (hasEntitlement, core#583).
Ein read-only MCP-Server exponiert die Daten für Agenten.
\nOwner-Entscheidung D5 (2026-07-08): neue Commerce/Payment-Addons. Revenue Cat
ist neu — kein bestehendes Aiopta-Addon deckt es ab (
payments→ Stripe/PayPal,
membership→ Abo-Modellierung, aber keines spricht Revenue Cat an).
- BYOK per-user (ADR-054): jeder User hinterlegt seinen eigenen Revenue Cat
projectId + Secret-API-Key über scopedStore(userId). Der Key wird nie
geloggt und nie über die API zurückgegeben (nur ein boolean hasApiKey).
- Graceful Read-Mode: ohne konfigurierten Key läuft das Addon im Lesemodus —
kein Default/Anonymous-Zugriff (INBOX-86-Analogie, wie das payments-Addon).
- User-Isolation: User A sieht nur seine eigenen Revenue-Cat-Daten
(user_id-Filter via scopedStore).
- Entitlement-Bridge: Revenue-Cat-Entitlements → Aiopta-Entitlement-Keys
(addon.<id> / rc.<id>), die mit dem Core-Gate (hasEntitlement,
hasAddonEntitlement, core#583) komponieren.
- MCP-Server (read-only): revenue-cat-tools exponiert Projektions-Tools für
Agenten (list_subscriptions, get_entitlements, get_customer,
list_offerings) — validiert gegen den #384-Contract.
Alle Endpunkte sind namespaced unter /api/v1/addons/revenue-cat. Daten-Endpunkte
benötigen customer_id (den Revenue Cat app user id) und einen konfigurierten Key.
| Methode | Pfad | Beschreibung |
|---|---|---|
| GET | /status | Konfiguriert? (boolean, kein Secret-Leak) |
| GET/POST | /config | BYOK-Config lesen/schreiben (Key nie zurückgegeben) |
| GET | /subscriptions?customer_id=<id>&active=true | Subscriptions eines Kunden |
| GET | /entitlements?customer_id=<id> | Entitlements + Aiopta-Keys |
| GET | /customer?customer_id=<id> | Customer-Info + Summary |
| GET | /offerings | Project-Offerings |
| GET | /widget | Dashboard-Key-Values (wirft nie) |
curl -X POST /api/v1/addons/revenue-cat/config \\\n -H 'Content-Type: application/json' \\\n -d '{"projectId":"abc123def","apiKey":"sk_xxx_…"}'Der apiKey (Secret-API-Key aus dem Revenue Cat Dashboard) wird per-user gespeichert
und nie zurückgegeben. projectId ist die Projekt-ID aus der Dashboard-URL.
revenue-cat-toolsEin Node-STDIO-Server (Contract #384), deklariert in addon.json → mcpServers[].
Permissions: ["addons/revenue-cat/read"], toolPolicy: read-only. BYOK-Slots:configRefs: ["projectId"], credentialRefs: ["apiKey"] (per Namen, nie Werte —
die Core-Runtime löst sie pro aufrufendem User auf, core#454).
Tools (alle read-only, annotiert readOnlyHint:true/destructiveHint:false):
list_subscriptions — aktive Subscriptions filternget_entitlements — aktive Entitlements → Aiopta-Keys (core#583)get_customer — Customer-Summary (aktive Abos, Entitlements, Käufe)list_offerings — Offerings/Packages projizierenValidierung: npm run test:mcp-servers (Konformanz-Suite entdeckt das Addon
automatisch) + scripts/addon-mcp-pilot-revenue-cat.test.cjs (Golden Values).
addons/revenue-cat/\n addon.json # Manifest + mcpServers[]-Deskriptor\n README.md\n src/\n lib/\n credential-store.ts # BYOK per-user via scopedStore (ADR-054)\n revenue-cat-client.ts # REST-API-Client (fetch, kein SDK), BYOK\n projections.ts # Pure Projektions-Helper (aktiv-Filter etc.)\n entitlement-bridge.ts # RC-Entitlements → Core hasEntitlement (core#583)\n app/api/v1/addons/revenue-cat/ # Routen (status, config, subscriptions, …)\n page.tsx # Read-only Management-Seite (Money-Section)\n mcp/servers/revenue-cat-tools/\n server.mjs # Read-only MCP-Server (faithful ports)\n tests/unit/\n manifest.test.ts\n revenue-cat-isolation.test.ts\n revenue-cat-graceful.test.ts\n revenue-cat-projections.test.tsNICHT anfassen: Core src/lib/entitlements.ts (nur konsumieren),src/lib/license/*, payments/membership-Addon-Internals, Core-Routen.
- Money-Stufe-1 (ADR-039). Webhook-Signature-Verifizierung folgt dem
payments-Muster (falls Webhooks implementiert werden).
- Rate-Limit von Revenue Cat → Backoff/Retry (client-seitig via Timeout).
- Ungültiger API-Key → HTTP 401, Fehleranzeige, keine stille Recovery.
npx vitest run addons/revenue-cat/tests/unit # Addon-Unit (BYOK, Isolation, Graceful, Projektionen)\nnpm run test:mcp-servers # MCP-Konformanz + Golden ValuesPer-User Reverse-Proxy-Monitoring (#515). BYOK-Verbindung zu Nginx Proxy
Manager, Traefik oder Caddy; listet Domains, Proxy-Routen und SSL-Zertifikate;
warnt vor bald auslaufenden Zertifikaten (warn / critical / expired) und
prüft die Health überwachter Routen.
- BYOK per User — jeder Nutzer hinterlegt seine eigene Proxy-Verbindung
(provider, base URL, token). Token wird gespeichert, aber niemals im
Klartext zurückgegeben (maskiert).
- Read-only gegenüber dem Proxy — das Addon mutiert nie eine Upstream-Route
oder ein Zertifikat. Es spiegelt und klassifiziert nur.
- Per-User isoliert — alle Daten via scopedStore + registerScopedTable
(ADR-054). Eine fremde id → 404 ohne Existenz-Leak.
- Cert-Expiry-Evaluator (pure) — `notAfter → days-remaining →
ok/warn/critical/expired/unknown`. Schwellen default 30/7 Tage.
- Gracious Degradation — ein nicht erreichbarer Proxy skippt die Verbindung,
statt die gesamte Anzeige scheitern zu lassen.
src/\n manifest.ts # Extension-Manifest (Routes + Page + install/uninstall)\n page.ts # Page-Deskriptor\n components/\n ReverseProxyPage.tsx # Dashboard (Domains / SSL / Health / Verbindungen)\n lib/\n rp-store.ts # scopedStore: connections, routes, certs\n cert-expiry-evaluator.ts # PURE: notAfter → days-remaining → level\n proxy-types.ts # neutrale Shapes + safeFetch + injectable fetch\n proxy-clients.ts # provider dispatch\n npm-client.ts # Nginx Proxy Manager (read-only)\n traefik-client.ts # Traefik (read-only)\n caddy-client.ts # Caddy admin API (read-only)\n app/api/v1/addons/reverse-proxy/\n config/route.ts + [id]/route.ts\n routes/route.ts + [id]/route.ts\n certs/route.ts\n health/route.ts\ntests/unit/\n cert-expiry.test.ts # reiner Evaluator (kein DB)\n proxy-clients.test.ts # fetch seam gemockt, provider-mapping\n reverse-proxy-isolation.test.ts # store-level per-user isolation| Method | Path | Beschreibung |
|--------|------|--------------|
| GET | /api/v1/addons/reverse-proxy/config | Verbindungen (maskiert) |
| POST | /api/v1/addons/reverse-proxy/config | Verbindung anlegen |
| DELETE | /api/v1/addons/reverse-proxy/config/:id | Verbindung entfernen |
| GET | /api/v1/addons/reverse-proxy/routes | Monitored domains (?sync=1 spiegelt Zertifikate) |
| POST | /api/v1/addons/reverse-proxy/routes | Domain überwachen |
| PATCH | /api/v1/addons/reverse-proxy/routes/:id | aktiv/inaktiv |
| DELETE | /api/v1/addons/reverse-proxy/routes/:id | entfernen |
| GET | /api/v1/addons/reverse-proxy/certs | Zertifikate + Expiry-Level + worst-Level |
| GET | /api/v1/addons/reverse-proxy/health | Probed aktiver Routen (up/down/unknown) |
Run an SEO content pipeline from inside Aiopta: research keywords, generate an AI article
draft, run on-page optimization, publish to WordPress, and track rankings. Usable by
agents (via the addon API) and by humans (via the management page). This is the second money tool in
the series (after dropshipping, ADR-013), covering REQUIREMENTS-AUDIT row 26 "SEO/Content".
keyword research → AI draft → on-page optimize → publish → rank-track\n (websearch) (gateway) (pure analyzer) (wordpress) (owner SaaS)The engine is deliberately a thin orchestrator over capabilities Aiopta already owns — it
adds no new direct integration except the owner-keyed rank tracker:
- AI generation goes through @/lib/gateway — never a direct LLM/provider call.
src/lib/article-generator.ts builds the prompt and calls chatCompletionWithFallbacks(...); the
gateway decides provider/backend routing. There is no provider fetch in this addon (a unit test
stubs global fetch and asserts it is never called during generation). The model returns a fenced
``json block which we strip + parse into { title, slug, markdown, metaDescription }`.
- Research builds on the consolidated research suite (websearch addon) via the Aiopta API.
src/lib/keyword-research.ts calls POST /api/v1/addons/websearch/search through the Aiopta API,
forwarding the caller's auth (RBAC preserved). It never re-implements search and never imports
the websearch addon directly. The raw SERP hits feed a pure scoring helper
(difficulty/opportunity) that is fully unit-tested.
- Publishing goes through the wordpress addon's Aiopta API — never WordPress directly.
src/lib/wordpress-bridge.ts calls POST /api/v1/addons/wordpress/posts (or /pages), forwarding
auth, and fails soft with a clear error if the wordpress addon is absent / not configured.
- The rank-tracker is an external SEO-data SaaS reached with the owner's key — NO container.
src/lib/rank-tracker.ts reads SEO_API_KEY (+ SEO_API_PROVIDER) from
getAddonConfiguration("seo-content") — the same owner-key pattern as the LLM providers and the
dropshipping suppliers. Provider base URLs (DataForSEO / SerpApi) are compile-time constants,
never a user-entered host; the key is sent as a Bearer token and never logged. A **missing key
returns a clean 400 before any fetch** (no unauthenticated call ever goes out).
- The pipeline owns a table. Unlike the dropshipping margins (a single config blob), the pipeline
has real state, so the addon owns seo_content_items, created in the extension install() and
dropped in uninstall() via Aiopta core's getDb(). On-page analysis (src/lib/on-page.ts) is pure
(no I/O) and unit-tested.
- Per-user isolation (#146 / ADR-054). seo_content_items carries user_id NOT NULL; all CRUD
goes through scopedStore(auth.id), the server stamps the owner from auth.id, and a foreign id
returns 404. A user only ever sees/edits/publishes/ranks their own articles, and on-page
optimization draws internal-link candidates only from the caller's own pipeline (never another
user's slugs). DDL runs via db.prepare(sql).run() (never db.exec); a legacy table is backfilled
to the first admin (logged) or its un-attributable rows dropped.
| Key | Required | Purpose |
|-----|----------|---------|
| SEO_API_KEY | for rank tracking | SEO-data SaaS API token (Bearer). Stored is_secret=1. |
| SEO_API_PROVIDER | optional | dataforseo (default) or serpapi. |
| SEO_API_LOCATION | optional | Default location/country code passed to the provider. |
Set them with setAddonConfiguration("seo-content", { SEO_API_KEY: "…" }). Keyword research and AI
drafting work without this key (they use the websearch addon + the gateway). Only rank tracking
needs it; until it is set, /status reports rankTracker.configured: false and /rankings returns a
clear 400.
All routes are namespaced under /api/v1/addons/seo-content/ and require auth.
GET /status → rank-tracker config + AI-gateway reachability + pipeline summary\nGET /keywords?q=… → research a query (via websearch) → scored suggestions\nGET /keywords → saved target keywords (stage = keyword)\nPOST /keywords { keyword } → save a target keyword into the pipeline\nGET /articles?stage= → list the pipeline (optionally by stage)\nPOST /articles { keyword, itemId?, … } → generate an AI DRAFT (via the gateway), persisted\nGET /articles/{id} → one pipeline item\nPUT /articles/{id} { title?, markdown?, metaDescription?, slug?, keyword? } → edit the draft\nDELETE /articles/{id} → remove a pipeline item\nPOST /articles/{id}/optimize → pure on-page analysis → score + recommendations (stage→optimized)\nPOST /articles/{id}/publish { type?, status? } → publish to WordPress via the wordpress addon (stage→published)\nGET /rankings?keywords=a,b&domain=&location= → live SERP positions (owner SEO key)\nGET /widget → flat key-values for the dashboard widgetResponses use the { "success": true, "data": … } envelope. On failure read error + the HTTP status
(a 400 on /rankings means SEO_API_KEY is not set; a publish/research failure forwards the
dependent addon's status).
src/lib/on-page.ts is pure + unit-tested. It scores a draft 0–100 from title/meta length, keyword
presence + density (healthy window 0.5–2.5%), word count, heading usage, and suggests internal links to
sibling pipeline items that share a meaningful term. No AI is involved — the model writes the draft;
this module measures it deterministically.
addons/seo-content/\n├── addon.json # Manifest (page + widget + endpoints + skills; NO container)\n├── README.md\n├── SKILL.md # Agent skill\n├── src/\n│ ├── manifest.ts # Extension (dual-registration; string-literal handlers; install/uninstall table)\n│ ├── page.tsx # Pipeline UI (Pipeline / Keyword Research / Rankings)\n│ ├── widget.tsx # Dashboard widget (pipeline counts + rank-tracker availability, declarative)\n│ ├── lib/\n│ │ ├── errors.ts # SeoContentError (HTTP-status-carrying)\n│ │ ├── keyword-research.ts # websearch via Aiopta-API + pure scoring (difficulty/opportunity)\n│ │ ├── article-generator.ts# prompt → @/lib/gateway → draft {title,slug,markdown,meta}; fence-strip\n│ │ ├── on-page.ts # PURE on-page analyzer (score + recommendations + internal links)\n│ │ ├── rank-tracker.ts # SEO-data SaaS client (SEO_API_KEY from Aiopta-config; missing key → 400)\n│ │ ├── wordpress-bridge.ts # publish via the wordpress addon's Aiopta-API (fail-soft)\n│ │ ├── content-store.ts # pipeline persistence (seo_content_items table via getDb)\n│ │ └── status.ts # /status payload (providers + gateway reachability + summary)\n│ └── app/api/v1/addons/seo-content/{status,keywords,articles,articles/[id],articles/[id]/optimize,articles/[id]/publish,rankings,widget}/route.ts\n└── tests/unit/ # manifest validity + pure on-page + pure scoring + gateway-routing + rank-tracker 400The addon code + routes work today: research uses the websearch addon, drafting uses the gateway,
publishing uses the wordpress addon. Only rank tracking needs an owner SEO key. Tracked indocs/OPEN-DECISIONS.md:
\nTODO(owner):
seo-data-provider-keys— create a DataForSEO or SerpApi key and store it in Aioptaaddon-config (
SEO_API_KEY, optionalSEO_API_PROVIDER). No secret is committed. Until set,
/statusreports rank tracking not-configured and/rankingsreturns a clear 400.
MIT
", "byteSize": 8332 } } }, { "id": "shopify", "uuid": "093be941-2064-484f-aba4-51b9e232ea08", "name": "Shopify", "version": "2.0.3", "description": "DEPRECATED — zusammengeführt in das kanonische Commerce-Addon `commerce` als Shopify-Connector (ADR-008 Addon-Konsolidierung, Issue #588 / Epic #492). Der Shopify-Channel ist als Feature-Modul unter `commerce/src/connectors/shopify/` migriert: BYOK-Credentials in der gemeinsamen `commerce_connector_config`-Tabelle, Sync-Client auf dem kanonischen `CommerceChannel`-Vertrag, Alt-ID-Redirect `/addons/shopify` → `/addons/commerce?connector=shopify`. shopify bleibt bis zum Sunset (2026-12-31) voll funktionsfähig und datenerhaltend — kein Endpoint entfällt, keine Zeile wird kopiert/gelöscht. Ursprüngliche Fähigkeit: Commerce channel: sync products, stock & orders from your Shopify shop via the Admin API (external SaaS). Each user brings their own access token (BYOK) stored per-user through the scoped data-access layer (ADR-054); no secret is hard-coded or logged and there is no container. Sync is always an explicit call.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "commerce-shopify", "shopify-products", "shopify-stock", "shopify-orders", "shopify-sync" ], "tags": [], "download": "/artifacts/shopify-2.0.3.zip", "sha256": "e8d3f950f9b3336dcc52bb7ba0d8567dcd5d740a9f1cf6796c2541d8905bd5d2", "size": 126361, "page": { "id": "shopify-page", "path": "/addons/shopify", "name": "Shopify", "icon": "🛍️", "section": "Money", "component": "@addons/shopify/src/page" }, "deprecated": true, "replacedBy": "commerce", "deprecation": { "deprecated": true, "replacedBy": "commerce", "sunset": "2026-12-31", "successorPath": "/addons/commerce", "successorLabel": "Commerce (Nachfolger)" }, "endpoints": [ "/api/v1/addons/shopify/status", "/api/v1/addons/shopify/config", "/api/v1/addons/shopify/products", "/api/v1/addons/shopify/stock", "/api/v1/addons/shopify/orders", "/api/v1/addons/shopify/sync" ], "skills": [ { "name": "shopify-sync", "displayName": "Shopify: Sync products / stock / orders", "description": "Trigger an explicit sync of the caller's Shopify shop (products, stock and orders) via the Admin API using the user's BYOK access token.", "permissions": [ "addons/shopify/sync", "addons/shopify/products", "addons/shopify/orders" ], "endpoint": "/api/v1/addons/shopify/sync", "scripts": [] }, { "name": "shopify-products", "displayName": "Shopify: Products & Stock", "description": "List the caller's cached Shopify products and stock levels, or write back a stock level to Shopify.", "permissions": [ "addons/shopify/products", "addons/shopify/stock" ], "endpoint": "/api/v1/addons/shopify/products", "scripts": [] }, { "name": "shopify-orders", "displayName": "Shopify: Orders", "description": "List the caller's cached Shopify orders.", "permissions": [ "addons/shopify/orders" ], "endpoint": "/api/v1/addons/shopify/orders", "scripts": [] } ], "mcpServers": [ { "id": "shopify-tools", "displayName": "Shopify tools", "description": "Read-only Shopify commerce-channel companion tools for agents: build the Admin API base URL from a shop domain, normalise product/variant payloads into the channel's CommerceProduct shape, roll up variant inventory, normalise order payloads, and summarise a sync result - faithful ports of the addon's src/lib modules (issue #442, epic #399). Mutates nothing; live per-user Shopify access is resolved core-side via the declared config/credential slots.", "transport": "stdio", "runtime": "node", "entry": "shopify-tools/server.mjs", "permissions": [ "addons/shopify/read" ], "toolPolicy": { "mode": "read-only", "allowDestructive": false }, "configRefs": [ "shopDomain", "apiVersion", "locationId" ], "credentialRefs": [ "accessToken" ], "archiveEntry": "shopify/mcp/servers/shopify-tools/server.mjs", "sha256": "cce740612ed7dd55be79f90bacf452f6170849e79c4fcb860ece95bef9676c18", "size": 20421, "descriptorVersion": 1 } ], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": null }, { "id": "skills", "uuid": "24b7741d-1b5c-4885-8fbc-9a2a90f0f4a4", "name": "Skills", "version": "1.0.12", "description": "Skill catalog, local skill management, ClawHub integration, and dynamic skill generation helpers.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "skills", "clawhub", "skill-repository", "dynamic-skills" ], "tags": [], "download": "/artifacts/skills-1.0.12.zip", "sha256": "5ec7f830daf4ef04c826fe5f7b93ba7309f0c98738eac32667348870b1bf1a2b", "size": 277438, "page": { "id": "skills", "path": "/addons/skills", "name": "Skills", "icon": "🧩", "section": "Agents", "component": "@addons/skills/src/components/skills/SkillsPage" }, "deprecated": false, "endpoints": [ "/api/v1/addons/skills", "/api/v1/addons/skills/clawhub", "/api/v1/addons/skills/repository" ], "skills": [ { "name": "skills-list", "displayName": "Skills: lokal auflisten", "description": "Listet die lokal installierten Skills aus dem Skills-Catalog. Reine Lese-Operation, kein Netzwerk-Call.", "permissions": [ "addons/skills/list" ], "endpoint": "/api/v1/addons/skills", "scripts": [ { "id": "skills-list-local", "name": "skills-list-local", "path": "skills-list/list.sh", "sha256": "fe3d0b5e133713889db65772d238994030924ce556ed1de662fd11ad90d8287e", "interpreter": "bash", "permissions": [ "addons/skills/list" ], "timeoutMs": 5000, "size": 864 } ] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "Skill catalog, local skill management, ClawHub integration, and dynamic skill generation helpers.
\nskills/skillsDas Addon hat zwei voneinander unabhängige Pfade:
\nLokale Skills liegen im Dateisystem. Seit der per-User-Isolation (#145 / INBOX-59 / ADR-054) liegen
die eigenen erstellten/installierten Skills eines Users unter dessen per-User-FS-Root
(resolveUserPath(user, "skills", "local", …), containment-checked) statt im früheren
prozessweiten …/skills/local. Diese funktionieren vollständig ohne externen Dienst:
Durchsuchen, SKILL.md ansehen/bearbeiten, neuen Skill anlegen, in einen Agent-Workspace deployen
(installSkillToWorkspace), aktivieren/deaktivieren — alles auf auth.id gescoped, sodass ein User
nie fremde Local-Skills sieht/ändert/löscht. Der lokale Browse-Pfad (GET /api/v1/skills) macht
keinen Netzwerk-Aufruf — eine fehlende/falsch konfigurierte Remote-Registry blockiert die lokalen
Skills nie.
Der geteilte Katalog (builtin-/Projekt-Skill-Verzeichnisse + die remote ClawHub-Registry) bleibt
instanzweit, read-only: er wird jedem User gelistet, aber nie per-User geschrieben, und ein
Katalog-Skill ist nicht als eigener Local-Skill löschbar. Nur die EIGENEN Local-Instanzen sind
gescoped.
Browse/Install/Sync entfernter Skills läuft entweder über das clawhub-CLI
(falls installiert) oder über einen HTTP-skill-repo-Dienst. Die Basis-URL
dieses Dienstes kommt aus der Aiopta-Addon-Konfiguration (SKILL_REPO_URL) bzw. dem
Env-Fallback — kein Host ist fest verdrahtet. Ist nichts konfiguriert, ist der
Remote-Pfad in einem klaren not-configured-Zustand (keine stillen Fehler): die UI
zeigt einen informativen Leerzustand mit Konfigurationshinweis statt einer leeren
Liste oder eines Dauer-Spinners.
\nSolange weder das CLI installiert noch eine Registry konfiguriert ist, sind die
Remote-Funktionen erwartungsgemäß deaktiviert. Das ist Owner-Infrastruktur und in
docs/OPEN-DECISIONS.md(clawhub-skill-registry) geparkt. **Lokale Skills sinddavon unberührt.**
Lokale Skills brauchen keine Konfiguration. Um die Remote-Registry zu aktivieren:
\n1. Entweder das clawhub-CLI im Aiopta-Container installieren (which clawhub muss
erfolgreich sein), oder
2. einen skill-repo-Dienst betreiben und dessen Basis-URL setzen — in der
Aiopta-Addon-Konfiguration des skills-Addons unter dem Schlüssel
SKILL_REPO_URL (z. B. https://skill-repo.example.com), oder ersatzweise
über die Umgebungsvariable SKILL_REPO_URL. Die Addon-Konfiguration hat Vorrang
vor der Env-Variable.
Erwartete HTTP-API des skill-repo-Dienstes (siehe SkillRepositoryClient insrc/lib/skills-repo.ts): GET /health, GET /api/stats, GET /api/skills,GET /api/skills/:name, …/versions, …/dependencies, …/dependents,GET /api/search, GET /api/categories, POST /api/sync,POST /api/skills/:name/{install,uninstall,update}. Ein leichtgewichtiger
Mock-Server für die Entwicklung liegt in src/lib/mock-skill-repo.ts.
GET /api/v1/skills/clawhub?action=status (oder …/repository?action=status)
liefert den echten Zustand:
{ "cliAvailable": false, "repoConfigured": false, "repoReachable": false, "repoUrl": "", "remoteAvailable": false }So weiß die UI, ob die Remote-Registry nicht konfiguriert, **konfiguriert aber
nicht erreichbar**, oder voll funktionsfähig ist.
| Methode(n) | Pfad | Zweck |
|---|---|---|
| GET, POST, PUT, DELETE | /api/v1/addons/skills | Lokale Skills (Filesystem) — browse, SKILL.md, create, deploy, toggle, delete |
| GET, POST | /api/v1/addons/skills/clawhub | ClawHub (CLI oder skill-repo); ?action=status |
| GET, POST | /api/v1/addons/skills/repository | Remote-Registry-Browse/Install/Sync; ?action=status |
- Remote-Registry (Browse/Install/Sync entfernter Skills) erfordert entweder das
clawhub-CLI oder einen konfigurierten skill-repo-Dienst (SKILL_REPO_URL).
Ohne beides ist der Remote-Pfad deaktiviert und zeigt einen klaren Hinweis —
lokale Skills funktionieren unabhängig davon. Geparkt in docs/OPEN-DECISIONS.md
(clawhub-skill-registry).
Per-User Smart-Home-Packs: kuratierte Home Assistant Automations- und Szenen-Vorlagen
(BYOK HA URL + Long-Lived-Token pro Nutzer), ein Pack-Browser mit Apply-Flow, ein
Live-Gerätestatus (device overview) sowie ein per-User Szenen-State. Lokale SQLite ist
die Quelle der Wahrheit für angewandte Packs + Szenen-State (ADR-054).
smart-home/addons/smart-homeJeder Nutzer bringt sein eigenes Home Assistant mit (BYOK): URL + Long-Lived-Token
werden per-User gespeichert (das Token verlässt niemals den Server — Clients sehen nurhasToken: boolean). Aus dem kuratierten Katalog wählt der Nutzer eine Automation- oder
Szenen-Vorlage, füllt die Platzhalter (z. B. motion_entity, light_entity) und wendet
sie an. Der reine pack-applier baut daraus das HA-Config-Payload, der Server POSTet es
an /api/config/<domain>/config/<id> der Nutzer-Instanz und lädt die Domain neu.
Angewandte Packs + Szenen-State werden per-User in SQLite gespeichert.
Der device-overview ist ein Best-Effort-Lesezugriff auf GET /api/states der
Nutzer-Instanz und degradiert graceful (connected: false) — ohne Verbindung oder bei
Netz-/Auth-Fehlern rendert die UI den "Verbinde dein HA"-Prompt statt zu crashen.
Keine Secrets im Addon selbst. Der Nutzer trägt seine eigenen HA-Credentials über den
"HA Connection"-Tab (oder POST /api/v1/addons/smart-home/config) ein. Ohne Verbindung
sind Katalog + Szenen nutzbar; das apply und der device-overview benötigen eine
aktive Verbindung.
| Methode(n) | Pfad |
|---|---|
| GET | /api/v1/addons/smart-home/packs |
| GET | /api/v1/addons/smart-home/packs/:id |
| GET, PATCH | /api/v1/addons/smart-home/scenes |
| GET | /api/v1/addons/smart-home/devices |
| GET, POST | /api/v1/addons/smart-home/config |
| DELETE | /api/v1/addons/smart-home/config/:id |
| POST | /api/v1/addons/smart-home/config/test |
| POST | /api/v1/addons/smart-home/apply |
- Das HA-Config-Payload wird bei jedem Apply neu aus der Vorlage + den gespeicherten
Platzhalter-Werten generiert (nie roh persistiert) — Vorlagen-Updates wirken beim
erneuten Anwenden.
- Der Reload der Domain nach dem Apply ist Best-Effort (reloaded: false möglich, wenn
HA den reload-Service einschränkt); der Config-Eintrag wird dennoch geschrieben.
- Szenen-State ist eine reine UI/Memory-Funktion; das tatsächliche HA-Szenen-Activation
passiert über das apply.
Multi-Plattform-Planung & -Posting für Aiopta (ADR-043).
\n## Was es kann
- Verfassen eines Beitrags für mehrere Plattformen, sofort posten oder
planen (scheduled_at).
- Redaktionskalender der geplanten Beiträge.
- KI-Caption über den Aiopta-Gateway (Thema → Vorschlag; wird nie automatisch gepostet).
- Basis-Analytics je Beitrag/Plattform (was die Plattform-API liefert).
## Plattformen
- Mastodon — voll implementiert. Konfiguration in Aiopta-Config:
MASTODON_INSTANCE (z. B. https://mastodon.social) + MASTODON_ACCESS_TOKEN.
- X / Instagram / Facebook / LinkedIn — an dieselbe Connector-Schnittstelle
modelliert; aktiv, sobald die Owner-OAuth-Apps konfiguriert sind
(siehe docs/OPEN-DECISIONS.md #75). Bis dahin meldet ein Post für diese
Plattformen graceful „nicht verbunden" (kein Fake-Erfolg).
## Sicherheit
- Posten ist eine authentifizierte Aktion; ohne verbundene Plattform → klares
400 („zuerst verbinden"), nie ein 500, nie ein stilles No-op.
- Tokens nur via Aiopta-Config, maskiert, nie geloggt.
- KI-Captions werden dem Nutzer zur Prüfung angezeigt, nicht automatisch versendet.
- Per-User-isoliert (#141 / ADR-054): Accounts, Beiträge und deren Plattform-
Targets tragen user_id und werden ausschließlich über scopedStore(auth.id)
gelesen/geschrieben. Der Server stempelt den Owner aus der Session (ein vom
Client geliefertes user_id wird ignoriert); eine fremde Beitrags-/Account-id
liefert 404 (nicht die Zeile). POST /scheduled/run-due ist ein
Per-User-Scheduler — jeder Aufruf veröffentlicht nur die EIGENEN fälligen
Beiträge.
## Endpoints/status, /accounts(+/:id), /posts(+/:id, /:id/publish), /scheduled/run-due,/ai/caption, /widget — alle unter /api/v1/addons/social-media/.
## PlanungPOST /scheduled/run-due veröffentlicht fällige geplante Beiträge — von einem
Cron/Scheduler (owner-konfiguriert) getriggert.
Bindet deine eigene Spoolman-Instanz als dual-mode connect-Addon in
Aiopta ein: Filament-Bestand lesen und die Restmenge fortschreiben.
Die Basis-URL ist ein Pflichtfeld ohne Vorgabe (baseUrl in den
Addon-Einstellungen). Es steht bewusst kein Hostname im Code: dieses Addon
liegt im gemeinsamen Bestand und wird an jede Aiopta-Installation
ausgeliefert — ein voreingestellter Wirt wäre der Produktivserver eines
Betreibers in der Installation aller anderen. Ist das Feld leer,
antworten alle Routen mit 409 spoolman_not_configured, und es geht kein
Netzruf raus.
Gemessen wurde gegen Spoolman 0.26.1 (git_commit f387203, Build
2026-08-07) auf der Instanz des Betreibers; die Befunde unten beziehen sich
auf diese Version.
Ticket: Aiopta/aiopta-addons#1126 (Kind von #1116).
Browser/Agent ──HTTPS──▶ Aiopta (dieses Addon) ──HTTPS──▶ Spoolman 0.26.1\n ├─ Dashboard (native DS-Seite) /addons/spoolman\n ├─ API-Routen (userRoute) /api/v1/addons/spoolman/…\n └─ MCP-Server (spoolman-tools) read-only- Natives Dashboard (src/page.tsx, ui.mode: "aiopta"): Spulen mit
Restmenge, used_length, extra-Feldern — und je Spule ein Feld für den
relativen Abzug in Millimetern. Ausschließlich @aiopta/ui-Komponenten;
der Browser kontaktiert Spoolman nie direkt.
- API-Routen (src/app/api/v1/addons/spoolman/*): zentrale Auth über
userRoute (Session-Cookie oder Bearer/X-API-Key Agent-Key).
- Client (src/lib/spoolman-client.ts): injizierbarer fetch-Seam
(Muster shopify-client.ts), damit kein Unit-Test je das Netz anfasst.
- Konfiguration (src/lib/config.ts): baseUrl (**Pflicht, kein
Default**) + apiKey (BYOK, password-Slot, optional). Fehlt baseUrl,
wirft getSpoolmanSettings() einen SpoolmanNotConfiguredError, bevor
irgendein fetch entsteht. Der Schlüssel verlässt den Server nie — auch
nicht maskiert in einem Fehlertext.
Alles hier ist am 2026-08-10 an der Anlage erhoben (Quellen:spoolman-offline-proxy/README.md §1, app/oben.py, app/kern.py;
Plugin-Quelltext auf dem OctoPi; GET /api/v1/openapi.json der Instanz).
PUT /spool/{id}/use ist relativ, in MillimeternDer Körper ist {"use_length": <mm>} — eine Länge, kein Gewicht. Das
OctoPrint-Spoolman-Plugin puffert mm (handleCommitSpoolUsage()). Gramm
entstehen nur für die Anzeige, aus filament.density undfilament.diameter.
Die absoluten Wege existieren (PUT /spool/{id}/measure,PATCH /spool/{id}) und werden hier nie benutzt: ein Absolutwert würde
eine zwischenzeitliche zentrale Korrektur überschreiben.
Geprüft an der OpenAPI-Beschreibung (30 Endpunkte):PUT /spool/{spool_id}/use nimmt genau spool_id im Pfad unduse_length/use_weight im Körper. Kein Idempotenzschlüssel, keinIf-Match, keine Vorgangs-ID, kein Buchungsbeleg.
Folge: doppelte Abbuchung lässt sich nur außerhalb von Spoolman
verhindern.
spoolman-offline-proxy — nicht hierDer Proxy (eigenes Repo, systemd-Dienst auf dem OctoPi) hältpending → sending → confirmed und gleicht über used_length ab
(app/kern.py::_erwartet_used, ::_schon_gebucht). **Dieses Addon baut
diese Logik nicht ein zweites Mal** — zwei Rechenstellen für dieselbe Frage
laufen auseinander.
Zwei Befunde, beide belegbar:
\n1. Der Proxy ist vom Aiopta-Server nicht erreichbar. Er bindet auf
127.0.0.1:7913 (spoolman-offline-proxy/beispiel.env:
PROXY_ADRESSE=127.0.0.1; README §5). Er sitzt hinter OctoPrint auf
dem OctoPi und soll dort bleiben — sein Zweck ist der Druckpfad bei
ausgefallener Powerline, nicht eine zweite Fernbedienung.
2. Die beiden Schreibpfade sind fachlich verschieden. Der Proxy bucht
den Druckverbrauch, ausgelöst vom Plugin, unbeaufsichtigt, über eine
unzuverlässige Leitung. Dieses Addon bucht eine *ausdrückliche
Korrektur*, ausgelöst von Mensch oder Agent, über eine normale Leitung.
Damit daraus trotzdem keine zweite Rechenstelle wird, gilt hier eine harte
Regel: das Addon misst und berichtet, es entscheidet nicht.
| | Proxy | dieses Addon |
|---|---|---|
| Warteschlange (pending/sending/confirmed) | ja | nein |
| Wiederholversuch | ja, abgesichert über used_length | nie |
| Schattenbestand / lokaler Cache | ja | nein |
| Entscheidung „schon gebucht?" | ja | nein — nur Messwerte im Bericht |
Bleibt der Ausgang eines Abzugs unklar (Zeitgrenze, Verbindungsabbruch),
antwortet die Route mit 409 booking_unclear und liefertusedLengthBefore + usedLengthProbe mit. Kein stiller Rückfall, kein
stiller zweiter Versuch — die Entscheidung liegt beim Menschen.
Basis: https://<instanz>/api/v1/addons/spoolman
| Ziel | Methode + Pfad | Permission |
|---|---|---|
| Bestand (Spulen, Filamente, Hersteller, extra) | GET /inventory | addons/spoolman/inventory/read |
| Eine Spule inkl. used_length | GET /spool/{id} | addons/spoolman/inventory/read |
| Relativen Abzug buchen | POST /spool/{id}/use | addons/spoolman/inventory/update |
# lesen\ncurl -s -H "Authorization: Bearer $AIOPTA_API_KEY" \\\n https://<instanz>/api/v1/addons/spoolman/inventory# einen Abzug von 1250 mm buchen (relativ!)
curl -s -X POST -H "Authorization: Bearer $AIOPTA_API_KEY" \\
-H 'content-type: application/json' \\
-d '{"use_length_mm": 1250}' \\
https://<instanz>/api/v1/addons/spoolman/spool/7/use
```
code)| Situation | Status | code |
|---|---|---|
| baseUrl nicht konfiguriert (kein Netzruf) | 409 | spoolman_not_configured |
| Spoolman nicht erreichbar | 502 | spoolman_unreachable |
| Spoolman antwortet mit unerwartetem Status | 502 | spoolman_upstream_error |
| Spule existiert nicht | 404 | spool_not_found |
| use_length_mm fehlt / ≤ 0 | 400 | invalid_use_length |
| Buchung unklar — nicht wiederholen | 409 | booking_unclear |
Erreichbar-und-leer ist etwas anderes als ausgefallen. Ein leerer
Bestand ist 200 { reachable: true, spools: [] }; ein Ausfall ist502 spoolman_unreachable. Die Oberfläche zeigt beides getrennt.
capabilityDeclarations, core#1078)| Capability | Tier | Permission |
|---|---|---|
| addons.spoolman.inventory.read | elevated | addons/spoolman/inventory/read |
| addons.spoolman.inventory.update | highest | addons/spoolman/inventory/update |
read ist elevated, nicht standard: die Rubrik indocs/ADDON-ADOPTION-STANDARD.md stuft bounded Egress (fixes,
BYOK-konfiguriertes Ziel) als elevated ein — Lesen ohne Egress wärestandard, dies hier verlässt aber die Instanz.
update ist highest, weil **ein falscher Abzug den Bestand still
verfälscht**: es fällt erst auf, wenn eine Rolle mitten im Druck leer ist.
ADR-062 (aiopta-core/src/lib/access/addon-trust.ts) ist eine
instanzweite, admin-gesetzte Eigenschaft je Addon
(trusted | standard | restricted, Default standard) — sie steht nicht
im Manifest, sondern in extensions.settings und wird indispatchExtensionRoute durchgesetzt. restricted verbietetPOST/PUT/PATCH/DELETE (isMethodAllowedForTrust).
Dieses Addon ist darauf ausgelegt:
\n| Trust-Stufe | Bestand lesen | Abzug buchen |
|---|---|---|
| trusted | ✅ | ✅ (zusätzlich Permission nötig) |
| standard (Default) | ✅ | ✅ (zusätzlich Permission nötig) |
| restricted | ✅ | ⛔ 403 vor dem Handler |
Deshalb liegt der Schreibpfad auf POST, nicht auf GET: nur ein
mutierendes Verb ist überhaupt sandboxbar. addons/spoolman/tests/unit/trust.test.ts
pinnt das gegen die echte Core-Funktion.
restricted ist die empfohlene Einstellung, solange nur gelesen werden
soll — dann ist das Addon nachweislich schreibunfähig, ohne es abzuschalten.
addonDependencies ist bewusst leer. Geprüft am 2026-08-10 gegen den
Bestand von 72 Addons: die naheliegenden Kandidaten heißen octoprint
und octoprint-proxy (beide existieren), aber es gibt keine
Laufzeitkopplung — dieses Addon liest und schreibt allein gegen Spoolman.
Eine required-Kante auf eine nicht existierende Addon-Id macht das Addon
nach ADR-047 uninstallierbar (addon_dependencies_unmet, HTTP 409,aiopta-core/src/lib/addons/dependency-check.ts:176/186). Eine Kante ohne
Kopplung wäre genau dieses Risiko ohne jeden Nutzen.
attestation.json) — StandDer Selbstausweis eines Addons ist die signierte attestation.json
(docs/ADDON-ADOPTION-STANDARD.md §2): declares.capabilities spiegeltcapabilityDeclarations, declares.touches trägt sha256 über jede
ausgelieferte Laufzeitdatei, signiert mit Ed25519 über kanonisches JSON.
Ohne sie zählt die Selbstauskunft nicht — „der Selbstausweis zählt **nur
kryptografisch verifiziert**".
Dieses Addon liefert sie noch nicht mit. Der private Schlüssel ist
absichtlich nicht im Repo: er lebt als Jenkins-Credentialaiopta-addon-signing-key und wird ausschließlich vom Jobci/Jenkinsfile.addonsign gebunden. Das Signieren ist damit ein
CI-Schritt, kein Entwickler-Schritt.
Nach dem Merge:
\nnode scripts/addon-adoption/attest.mjs generate spoolman # im Signier-Job\nnode scripts/addon-adoption/attest.mjs verify spoolmanDanach muss der Eintrag spoolman aus BEKANNTE_LUECKEN inscripts/check-addon-adoption.cjs entfernt werden — der Validator macht
den Lauf sonst rot (veralteteAusnahmen), und das ist Absicht.
spoolman-tools)Read-only, stdio/node, Permission addons/spoolman/inventory/read,toolPolicy: { mode: "read-only", allowDestructive: false }.
| Tool | Zweck |
|---|---|
| spool_list | Spulen mit Restmenge (inkl. extra) |
| spool_get | eine Spule inkl. used_length |
| filament_list | Filamente (Material, Farbe, Dichte, Preis) |
| vendor_list | Hersteller |
Es gibt bewusst kein schreibendes Tool. Ein Agent, der bei unklarer
Antwort noch einmal ruft, bucht doppelt — und genau das kann Spoolman 0.26.1
nicht abwehren. Der schreibende Pfad läuft ausschließlich über die
API-Route mit eigener, höchster Trust-Stufe.
Slots (nie als Tool-Argument): AIOPTA_CONFIG_BASEURL,AIOPTA_CREDENTIAL_APIKEY.
npm run test:unit -- addons/spoolman # vitest (Manifest, Client, Routen, Trust)\nnode --test scripts/addon-mcp-conformance.test.cjs # MCP-Konformanz (deckt spoolman automatisch)Die Negativ-Fälle des Tickets sind einzeln gepinnt:
\n- Fortschreiben ohne Berechtigung → typisierte Ablehnung, **und der Bestand
ist danach nachweislich unverändert** (nicht nur „ein Fehler kam").
- Spoolman nicht erreichbar → erklärter Zustand, unterscheidbar von einem
leeren Bestand.
- Der Zugang taucht in keiner Antwort auf, auch nicht maskiert in einem
Fehlertext.
Owner, 2026-08-04: „erst muss der Kundenauftrag durchgehen." Der
Slice-Dienst auf CT 123 läuft produktiv. **Lesen und messen: ja. Ändern
oder neu starten: nein.** Dieses Addon wurde ausschließlich gegen Stubs
entwickelt; kein Test und kein Build-Schritt spricht mit der echten
Spoolman-Instanz.
Task board UI and task APIs as an installable addon.
\ntask-board/tasksKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials.
\n| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/task-board |
| GET, PUT, DELETE | /api/v1/addons/task-board/[id] |
| GET, POST, DELETE | /api/v1/addons/task-board/[id]/attachments |
| GET, POST | /api/v1/addons/task-board/[id]/comments |
| GET, POST, DELETE | /api/v1/addons/task-board/[id]/dependencies |
| GET, POST | /api/v1/addons/task-board/[id]/subtasks |
| GET, POST, DELETE | /api/v1/addons/task-board/[id]/time |
| GET, POST | /api/v1/addons/task-board/comments/destinations |
| GET | /api/v1/addons/task-board/kanban/[boardId]/analytics |
| GET, POST, PUT, DELETE | /api/v1/addons/task-board/kanban/[boardId]/columns |
| GET | /api/v1/addons/task-board/kanban/[boardId]/export |
| GET, POST | /api/v1/addons/task-board/kanban/[boardId]/swimlanes |
| GET, POST | /api/v1/addons/task-board/kanban/boards |
| GET | /api/v1/addons/task-board/search |
| GET | /api/v1/addons/task-board/status |
| GET, POST | /api/v1/addons/task-board/tasks |
| GET, PUT, DELETE | /api/v1/addons/task-board/tasks/[id] |
| GET | /api/v1/addons/task-board/tasks/search |
| GET, POST | /api/v1/addons/task-board/templates |
", "byteSize": 1678 } } }, { "id": "trading", "uuid": "97c0b487-8e82-46ee-abb1-1a335c48ea5e", "name": "trading", "version": "1.56.10", "description": "Hyperliquid trading extension with real-time orders, positions, journal, workflow automation, self-contained market research tooling, DST-safe pre-market/weekly-review scheduler (issue #153), market-open/midday-scan safe-execute dispatcher (issue #154), and a deterministic, per-user lesson tracker (issue #116)", "author": "Aiopta", "icon": "🧩", "capabilities": [ "trading", "orders", "positions", "journal", "autotrading", "strategy-automation", "risk-management", "research", "scheduler", "planner", "executor", "workflow", "gov-scanner" ], "tags": [], "download": "/artifacts/trading-1.56.10.zip", "sha256": "4f6f597f5f6c513508dc6597dabddc62b3d0664bfe80f5fb1fe389d298341929", "size": 2601164, "page": { "path": "/addons/trading", "name": "Trading", "icon": "📊", "section": "Finance", "component": "@addons/trading/src/components/TradingPage" }, "deprecated": false, "endpoints": [ "/api/v1/addons/trading/account", "/api/v1/addons/trading/analyze", "/api/v1/addons/trading/autotrading", "/api/v1/addons/trading/buy", "/api/v1/addons/trading/charts", "/api/v1/addons/trading/close", "/api/v1/addons/trading/config", "/api/v1/addons/trading/gov-config", "/api/v1/addons/trading/gov-config/test-webhook", "/api/v1/addons/trading/gov-proposals", "/api/v1/addons/trading/gov-proposals/[id]/decide", "/api/v1/addons/trading/gov-prices", "/api/v1/addons/trading/gov-scan", "/api/v1/addons/trading/gov-signals", "/api/v1/addons/trading/gov-signals/[id]", "/api/v1/addons/trading/gov-sources", "/api/v1/addons/trading/gov-issuers/refresh", "/api/v1/addons/trading/history", "/api/v1/addons/trading/hyperliquid", "/api/v1/addons/trading/journal", "/api/v1/addons/trading/lessons", "/api/v1/addons/trading/market/{category}", "/api/v1/addons/trading/orders", "/api/v1/addons/trading/positions", "/api/v1/addons/trading/report", "/api/v1/addons/trading/research/fetch", "/api/v1/addons/trading/research/search", "/api/v1/addons/trading/risk", "/api/v1/addons/trading/sell", "/api/v1/addons/trading/settings", "/api/v1/addons/trading/sl", "/api/v1/addons/trading/stats", "/api/v1/addons/trading/status", "/api/v1/addons/trading/stop-loss", "/api/v1/addons/trading/strategies", "/api/v1/addons/trading/strategies/ladder", "/api/v1/addons/trading/strategies/preview", "/api/v1/addons/trading/workflow", "/api/v1/addons/trading/workflow-config", "/api/v1/addons/trading/workflow/run" ], "skills": [ { "name": "trading-status", "displayName": "Trading: Account & Positions", "description": "Read Hyperliquid account value, open positions and live status", "permissions": [ "addons/trading/status", "addons/trading/positions", "addons/trading/account" ], "endpoint": "/api/v1/addons/trading/status", "scripts": [ { "id": "trading-status-cli", "name": "trading-status-cli", "path": "trading-status/cli.sh", "sha256": "6da8c8486514f36922ec398642274a0c57528fbdd70b4f58716ebd91b977d145", "interpreter": "bash", "timeoutMs": 10000, "permissions": [ "addons/trading/account", "addons/trading/positions", "addons/trading/status" ], "inputSchema": { "type": "object", "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "timeoutMs": { "type": "integer", "minimum": 100, "maximum": 300000 } } }, "outputSchema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "integer" }, "data": {}, "error": { "type": "string" }, "truncated": { "type": "boolean" } } }, "size": 12083 } ] }, { "name": "trading-orders", "displayName": "Trading: Place & Manage Orders", "description": "Open/close positions and place limit orders on Hyperliquid perps", "permissions": [ "addons/trading/buy", "addons/trading/sell", "addons/trading/close", "addons/trading/orders" ], "endpoint": "/api/v1/addons/trading/orders", "scripts": [] }, { "name": "trading-risk", "displayName": "Trading: Risk & Stop-Loss", "description": "Set stop-loss orders and read risk metrics for open positions", "permissions": [ "addons/trading/stop-loss", "addons/trading/sl", "addons/trading/risk" ], "endpoint": "/api/v1/addons/trading/risk", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Crypto trading integration for Aiopta, powered by Hyperliquid.
\nresearch-tools addon instead of duplicating search logickrabcli.pin.json at commit 487b7895a65d53bfa698a17583fbf6d61342e325); matrix loader at src/lib/krabcli/parity.ts and sub-process wrapper at src/lib/krabcli/runner.ts. See docs/KRABCLI-PARITY.md for the 17-row evidence document.Rule-based strategy engines (no LLM needed) under src/lib/. Each is a pure,
unit-tested planner; execution goes through the normal order path with the
strategy guard-rails (dryRun, daily-trade and exposure caps).
| Strategy | Module | Execution on Hyperliquid | Notes |
|----------|--------|--------------------------|-------|
| Percentage trailing stop | stop-manager.ts + strategy-config.ts | ✅ full | Price-based floor that only ratchets up (longs) / down (shorts); places the SL via engine.setStopLoss. |
| Ladder buys / DCA | ladder-executor.ts | ✅ full | Staged limit buys at dip thresholds, double-execution-guarded in DB. |
| Wheel strategy (#236) | wheel-strategy.ts | ⚠️ advisory only | The cash-secured-put → assignment → covered-call cycle state machine and per-cycle premium accounting are implemented and tested. Limitation: Hyperliquid has no options, so there is no execution backend — planWheelCycle returns advisoryOnly plans (paper). Strike selection uses a delta-as-moneyness heuristic; wiring an options-capable provider (Tradier/Alpaca/IBKR) through a WheelExecutionAdapter + a live options chain would make it executable. |
| Copy trading / smart money (#237) | copy-trading.ts | ✅ executable, ⚠️ needs data source | The mirroring engine (conviction sizing, USD cap, confidence/lag filters, allow/deny lists, manual-approval gate) is implemented and tested; mirrored orders are normal perp orders. Limitation: the data source — which trades to copy (CapitolTrades/Quiver politician filings, whale wallets) — is external and not wired. Feed trades via the ObservedTrade shape; a future provider implements the CopyTradeProvider interface. |
Strategy config lives in strategy-config.ts (StrategyAutomationConfig) and is
editable through the Trading settings UI.
All endpoints require API key authentication (Authorization: Bearer <key>).
Addon runtime routes are exposed under /api/v1/addons/trading/....
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/v1/trading/status | Full portfolio status with positions |
| GET | /api/v1/trading/account | Account balance, margin, capital summary |
| GET | /api/v1/trading/positions | Open positions only |
| GET | /api/v1/trading/orders | Open orders |
| POST | /api/v1/trading/orders | Place limit/stop/TP order |
| POST | /api/v1/trading/buy | Open long position |
| POST | /api/v1/trading/sell | Open short position |
| POST | /api/v1/trading/close | Close position by coin |
| POST | /api/v1/trading/stop-loss | Set stop-loss for position |
| GET | /api/v1/trading/history | Closed-trade history (canonical, KRABCLI history, max 30, per-user) |
| GET | /api/v1/trading/stats | Performance statistics (canonical, KRABCLI stats, per-user) |
| GET | /api/v1/trading/report | Daily report (template-versioned, idempotent, KRABCLI report) |
| GET | /api/v1/trading/charts | Chart data |
| GET | /api/v1/trading/risk | Risk metrics |
| GET | /api/v1/trading/journal | Trading journal entries |
| GET | /api/v1/trading/lessons | Learned lessons |
| GET | /api/v1/trading/analyze | AI trade analysis |
| GET | /api/v1/trading/research/search | Search web research sources |
| GET | /api/v1/trading/research/fetch | Extract readable source content |
| GET | /api/v1/trading/autotrading | Auto-trading config |
| GET | /api/v1/addons/trading/strategies | Mr Krabs strategy automation settings |
| PATCH | /api/v1/addons/trading/strategies | Update percentage trailing, DCA, wheel, copy-trading and guard-rail settings |
| POST | /api/v1/addons/trading/strategies/preview | Preview strategy effects for a supplied market snapshot |
| GET | /api/v1/trading/workflow | Recent workflow runs |
| POST | /api/v1/trading/workflow/run | Run a workflow phase manually |
| POST | /api/v1/trading/hyperliquid | Webhook for trade fills/cancels/liquidations |
GET /api/v1/addons/trading/history, GET /api/v1/addons/trading/stats
and GET /api/v1/addons/trading/report are the canonical surfaces
that mirror the KRABCLI commands history, stats, report. They
read from the per-user trades table (scopedStore(userId), ADR-054)
so a user can never see another user's positions or PnL — the row-level
isolation is enforced in the SQL layer, not in JS.
/history)- Closed trades only (status = 'closed'). Open / cancelled rows never
leak through.
- Sort key: closed_at DESC, id DESC (deterministic tie-break).
- Hard cap: 30 rows (the KRABCLI parity contract). Bumping this
constant is a contract change — update both this file and
addons/trading/src/lib/history.ts: CANONICAL_HISTORY_LIMIT.
- Each row carries its own fxRate, fxFetchedAt, fxStale
triple so a downstream consumer can render `USD (1.10 EUR, fetched
2 min ago)`-style labels without re-resolving the FX snapshot.
/stats)All formulas are pinned by the golden-fixture tests intests/unit/performance-canonical.test.ts. Sample size, all rates and
the Sharpe are computed from the per-user closed-trade ledger only
(ADR-054). When sampleSize = 0 the response returns neutral zeros
plus fx/degraded metadata.
| Metric | Formula |
|---|---|
| winRate | wins / sampleSize (rounded to 4 dp) |
| lossRate | losses / sampleSize (rounded to 4 dp) |
| sharpe | (mean(pnlUsd) / sampleStd(pnlUsd)) * sqrt(252) (annualised; sqrt(252) is the documented trading-day convention for the KRABCLI parity matrix). Undefined for sampleSize ≤ 1 → returns 0. |
| maxDrawdownUsd | max(peak_cumulative - cumPnL_i) over the chronological pnl series (USD, rounded to cents) |
| avgDurationHours | mean(closed_at - opened_at) across rows where both timestamps parse |
| medianDurationHours | median of the same duration array (rounded to 4 dp) |
| totalPnlUsd / totalPnlEur | sum(pnl_usd) / sum(pnl_eur) (USD rounded to cents, EUR to cents) |
| totalFeesUsd | sum(fees_usd) (column added by issue #115 migration) |
| bestTradeUsd / worstTradeUsd / avgPnlUsd | max / min / mean of per-trade pnl_usd |
Changing any of these is a contract change — update the README, the
golden-fixture test, and performance.ts together.
fx.ts)- TTL: 1 hour (FX_TTL_MS = 3 600 000 ms). A cache entry older
than the TTL is served as stale: true, never as fresh.
- Provider: Frankfurter API (https://api.frankfurter.app/latest),
with a 5 s per-request timeout (FX_REQUEST_TIMEOUT_MS).
- No invented rates. When the provider fails AND no cache entry
exists, the snapshot returns rate: 1 with source: 'provider-failed'
and stale: true. The route layer surfaces degraded: true so the
UI tells the user "we don't know the rate right now" instead of
silently picking a number.
- Per-trade FX pricing is the canonical source — each closed-trade
row stores its own eur_usd_rate (USD → EUR) plus fx_rate_at
timestamp (ISO), written at close time. Legacy rows that pre-date
the column fall back to the live snapshot and get tagged
fxStale: true. The route payload exposes both the per-row FX and
the batch-level FX snapshot so the consumer can choose which to
surface.
report (/report)The report command is the MISSING-CONTRACT from the KRABCLI
parity matrix (issue #156, row cmd-report). The Aiopta route is:
- Read-only, template-versioned (templateVersion: "1.0.0"), no order
mutation.
- Idempotent per (userId, date) — the response carries an
idempotencyKey (FNV-1a over (userId, date, stats)) so a cron
retry on the same day produces the same key and the same body.
- Date defaults to today (UTC); ?date=YYYY-MM-DD for back-fills.
research-tools addon.### Check Account Balance
```bash
curl -H "Authorization: Bearer $API_KEY" \\
https://aiopta.example.com/api/v1/trading/account
```
### Open a Long Position (BTC, $100 margin, 20x leverage, 5% stop-loss)
```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"coin":"BTC","size":100,"leverage":20}' \\
https://aiopta.example.com/api/v1/trading/buy
```
### Open a Short Position
```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"coin":"ETH","size":200,"leverage":10}' \\
https://aiopta.example.com/api/v1/trading/sell
```
### Place a Limit Order
```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"coin":"BTC","side":"BUY","type":"LIMIT","size":0.1,"price":80000}' \\
https://aiopta.example.com/api/v1/trading/orders
```
### Trade a Builder-Deployed Perp
```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"coin":"xyz:NVDA","side":"BUY","type":"MARKET","size":1}' \\
https://aiopta.example.com/api/v1/trading/orders
```
### Set Stop-Loss
```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"coin":"BTC","price":79000}' \\
https://aiopta.example.com/api/v1/trading/stop-loss
```
### Close Position
```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"coin":"BTC"}' \\
https://aiopta.example.com/api/v1/trading/close
```
### Get Daily P&L Summary
```bash
curl -H "Authorization: Bearer $API_KEY" \\
https://aiopta.example.com/api/v1/trading/stats
```
### Run A Pre-Market Workflow
```bash
curl -X POST -H "Authorization: Bearer $API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"phase":"pre_market"}' \\
https://aiopta.example.com/api/v1/trading/workflow/run
```
Set these environment variables:
\nHYPERLIQUID_ADDRESS=0x...\nHYPERLIQUID_PRIVATE_KEY=0x...Enable/disable via Admin API:
```bash
# Check status
curl -H "Authorization: Bearer $API_KEY" \\
https://aiopta.example.com/api/v1/admin/extensions
# Disable trading
curl -X POST -H "Authorization: Bearer $API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"id":"trading","enabled":false}' \\
https://aiopta.example.com/api/v1/admin/extensions
```
Created on install:
- trades — All trade records (open/closed/cancelled)
- orders — Limit/stop/TP orders
- lessons — Trading lessons learned
- daily_snapshots — Capital snapshots per day
Wertet öffentliche Pflichtmeldungen und Vergabebekanntmachungen aus. **Keine
Insider-Tipps** — ausschliesslich Quellen, deren Veröffentlichung gesetzlich
vorgeschrieben ist.
| Kennung | Art | liefert | Zugangsdaten |
|---|---|---|---|
| usaspending | Vergabe | US-Bundesvergaben | keine |
| sec_form4 | Meldung | Insidergeschäfte (SEC Form 4) | gov.sec_user_agent |
| stock_act | Meldung | Offenlegungen des US-Kongresses | gov.stock_act_user_agent |
| ted | Vergabe | EU-Vergabebekanntmachungen | gov.ted_user_agent |
| eu_transparency | Meldung | Stimmrechtsmitteilungen (EU) | gov.eu_transparency_user_agent |
| bundesanzeiger | Meldung | Directors' Dealings (Art. 19 MAR) | gov.bundesanzeiger_api_key |
Alle sechs stehen nach install() in gov_sources — auch die ohne
Zugangsdaten. Eine leere Liste wäre von „sechs Quellen, alle unkonfiguriert"
nicht zu unterscheiden, obwohl das eine ein Zustand und das andere eine
Aufgabenliste ist.
Vergabe- und Meldequellen unterscheiden sich in der Richtung. Eine Vergabe
ist ein Zufluss: sie kann BUY oder NEUTRAL begründen, nie SELL. Nur
Meldequellen nennen den Geschäftsvorfall und damit auch einen Verkauf.
gov_sources.last_status trägt einen von vier Werten:
| Wert | heisst |
|---|---|
| NULL | noch nie gelaufen |
| ok | die Quelle hat geantwortet |
| not_configured | es fehlt eine Angabe, die nur der Betreiber liefern kann |
| unreachable | die Angabe ist da, die Quelle antwortet nicht |
Die letzten beiden sehen an der Oberfläche gleich aus („keine Daten"), sind
aber verschiedene Dinge: das eine ist eine Aufgabe für den Betreiber, das
andere eine Störung, die von selbst vergeht. Eine gestörte Quelle bricht den
Gesamtscan nicht ab — sonst sähen die übrigen aus wie „nichts Neues
gefunden", obwohl sie nie gefragt wurden.
| Recht | erlaubt |
|---|---|
| addons.trading.gov.read | Quellenliste, Treffer, Beleg, Backtest, Konfiguration lesen |
| addons.trading.gov.configure | Quellen an/aus, Schwellen, Webhook, Scan auslösen |
Die Gov-Daten sind instanzweit (ADR-054), nicht nutzergebunden — es gibt
kein Besitzerprädikat. Die Vorschlagsliste (/gov-proposals) ist die Ausnahme:
sie gehört dem Nutzer und wird über user_id gebunden.
resolveIssuer löst einen gemeldeten Namen gegen gov_issuers auf und liefert
einen von drei Zuständen:
| Zustand | heisst |
|---|---|
| resolved | genau ein Treffer, ticker ist gesetzt |
| ambiguous | mehrere Treffer, candidates nennt sie |
| unresolved | kein Treffer |
unresolved lässt die Meldung nicht verschwinden. Der Entwurf trägt dannticker: null und bleibt sichtbar; nur zum Handelssignal wird er nicht. Eine
frühere Fassung liess solche Meldungen fallen — damit war die Zahl der
gefundenen Vorgänge systematisch zu klein, ohne dass es jemand sah.
Die Auflösung vergleicht exakt auf der normalisierten Form. Eine frühere
beidseitige Teilstring-Heuristik erzeugte belegbare Falschtreffer
("AMAZONIA CONSTRUCTORA LTDA" → AMZN, "CO" → AIR) — und aus einem
Falschtreffer wird kein Anzeigefehler, sondern ein Handelssignal auf das
falsche Papier.
Ohne konfigurierte Kursquelle gibt es keine Trefferquote — und 0 % wäre
die schlechteste aller Antworten: sie sieht aus wie eine Messung und heisst
„alles verloren". Jedes Ergebnis trägt deshalb entweder Zahlen oder einen
Grund:
| Grund | wann |
|---|---|
| no_price_source | keine Kursreihe vorhanden |
| insufficient_sample | weniger als 8 auswertbare Signale |
| no_price_at_signal | dieses Signal hat keinen Kurs am Signaltag |
| horizon_incomplete | der Horizont reicht über das Ende der Reihe hinaus |
Die letzten beiden gelten je Signal und schliessen es aus der Stichprobe aus,
ohne die ganze Rechnung zu verwerfen. Fenster: 24 Monate Rückblick, 20
Handelstage Horizont.
lib/trading/\n├── client.ts # Hyperliquid SDK wrapper\n├── engine.ts # Core trading: buy, sell, close, stop-loss\n├── orders.ts # Order types: market, limit, stop, take-profit\n├── performance.ts # Stats, history, snapshots\n├── fx.ts # EUR/USD rate\n├── charts.ts # Chart data\n├── risk.ts # Risk calculations\n├── journal.ts # Trading journal\n├── lessons.ts # AI lessons\n├── autotrading.ts # Auto-trading config\n└── websocket.ts # Real-time feedsapp/api/v1/trading/ # API routes (16 endpoints)
extensions/trading/ # Extension manifest & registration
```
Per-User Reisen: Trips mit Etappen (Timeline), Unterkünften, POIs, Packliste, pro-Trip Budget (Rollup aus Etappen + Unterkünften) und einer Karte. Lokale SQLite ist die Quelle der Wahrheit (ADR-054).
\ntrip-planner/addons/trip-plannerKeine Secrets erforderlich — funktioniert ohne zusätzliche Credentials. Die Karte
ist eingebettet (Equirectangular-Projektion über Lat/Lng der Etappen/Unterkünfte/POIs)
und benötigt keine externen Tile-Provider.
| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/trip-planner/trips |
| PATCH, DELETE | /api/v1/addons/trip-planner/trips/[id] |
| GET, POST | /api/v1/addons/trip-planner/stages |
| PATCH, DELETE | /api/v1/addons/trip-planner/stages/[id] |
| GET, POST | /api/v1/addons/trip-planner/accommodations |
| DELETE | /api/v1/addons/trip-planner/accommodations/[id] |
| GET, POST | /api/v1/addons/trip-planner/pois |
| DELETE | /api/v1/addons/trip-planner/pois/[id] |
| GET, POST | /api/v1/addons/trip-planner/packing |
| PATCH, DELETE | /api/v1/addons/trip-planner/packing/[id] |
| GET | /api/v1/addons/trip-planner/budget |
Alle Endpunkte sind per userRoute authentifiziert und per scopedStore(auth.id)
per-User gebucht (ADR-054). Ein fremdes/fehlendes id -> 404 ohne Existenz-Leak.
Das Löschen einer Reise kaskadiert auf deren Etappen/Unterkünfte/POIs/Packliste.
GET /budget?tripId= liefert den Rollup: geplante Ausgaben (Summe aus Etappen-
+ Unterkünfte-Kosten) gegen das Reise-Budget, mit remaining, percentUsed undoverBudget. Zusätzlich wird der Pack-Fortschritt (packed/total, percent)
zurückgegeben.
", "byteSize": 2063 } } }, { "id": "voice", "uuid": "9777b5eb-54ad-488b-b622-1f7724eb6007", "name": "Voice", "version": "1.1.3", "description": "Unified voice addon combining Text-to-Speech and Speech-to-Text with multiple backend support.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "tts", "stt", "voice", "audio" ], "tags": [], "download": "/artifacts/voice-1.1.3.zip", "sha256": "a26b4e69a457e29e2b6a8f07f7601d643ecdf273a4b80ba0411b2bbba92a877b", "size": 148337, "page": { "path": "/addons/voice", "name": "Voice", "icon": "🎤", "section": "Settings", "component": "@addons/voice/src/ui/VoiceSettings" }, "deprecated": false, "endpoints": [ "/api/v1/addons/voice/health", "/api/v1/addons/voice/status", "/api/v1/addons/voice/start", "/api/v1/addons/voice/stop", "/api/v1/addons/voice/synthesize", "/api/v1/addons/voice/transcribe", "/api/v1/addons/voice/voices", "/api/v1/addons/voice/backends", "/api/v1/addons/voice/backend/switch", "/api/v1/addons/voice/settings", "/api/v1/addons/voice/tools/synthesize", "/api/v1/addons/voice/tools/transcribe", "/api/v1/addons/voice/tools/voice-proxy", "/api/v1/addons/voice/tools/voice-reply", "/api/v1/addons/voice/tools/voice-reply-external" ], "skills": [], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Unified voice addon combining Text-to-Speech and Speech-to-Text with multiple backend support.
\nvoice/addons/voiceDieses Addon benötigt folgende Secrets/Provider-Konfiguration (Settings → Credentials bzw. Provider-Store, nie in addon.json):
\nAWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEYAWS_STT_ACCESS_KEY_IDAWS_STT_SECRET_ACCESS_KEYAZURE_STT_SUBSCRIPTION_KEYELEVENLABS_API_KEYGOOGLE_STT_API_KEYGOOGLE_TTS_API_KEY| Methode(n) | Pfad |
|---|---|
| POST | /api/v1/addons/voice/backend/switch |
| GET | /api/v1/addons/voice/backends |
| GET | /api/v1/addons/voice/health |
| GET, POST | /api/v1/addons/voice/settings |
| POST | /api/v1/addons/voice/start |
| GET | /api/v1/addons/voice/status |
| POST | /api/v1/addons/voice/stop |
| POST | /api/v1/addons/voice/synthesize |
| GET, POST | /api/v1/addons/voice/tools/synthesize |
| GET, POST | /api/v1/addons/voice/tools/transcribe |
| GET, POST | /api/v1/addons/voice/tools/voice-proxy |
| GET, POST | /api/v1/addons/voice/tools/voice-reply |
| GET, POST | /api/v1/addons/voice/tools/voice-reply-external |
| POST | /api/v1/addons/voice/transcribe |
| GET | /api/v1/addons/voice/voices |
", "byteSize": 1582 } } }, { "id": "vpn", "uuid": "9cdda8a9-9ac1-4548-b49d-fb20573ec8f0", "name": "VPN (WireGuard / Tailscale — Peers, Status & Konfig-QR)", "version": "1.0.4", "description": "Per-User VPN-Verwaltung: BYOK-Verbindung zu WireGuard (wg-easy API) oder Tailscale (API). Listet Peers (connected/disconnected), zeigt Peer-Status (Handshake/Transfer), generiert Konfig-QR (WireGuard-Peer-Config → QR-Data-URI) und legt Peers an/entfernt. Read/Write gegenüber dem eigenen VPN-Server, vollständig per-User über scopedStore isoliert (ADR-054).", "author": "Aiopta", "icon": "🔒", "capabilities": [ "vpn", "wireguard", "tailscale", "peers", "peer-status", "config-qr", "connections" ], "tags": [], "download": "/artifacts/vpn-1.0.4.zip", "sha256": "045b522f03c97981480f6bf0eb4f9d3d95aac4dcc813d684d84aeb76fd5b318c", "size": 120933, "page": { "id": "vpn-page", "path": "/addons/vpn", "name": "VPN", "icon": "🔒", "section": "Infra", "component": "@addons/vpn/src/components/VpnPage" }, "deprecated": true, "replacedBy": "network", "deprecation": { "deprecated": true, "replacedBy": "network", "sunset": "2026-12-31", "successorPath": "/addons/network", "successorLabel": "Network/Homelab (Nachfolger)" }, "endpoints": [ "/api/v1/addons/vpn/config", "/api/v1/addons/vpn/config/:id", "/api/v1/addons/vpn/peers", "/api/v1/addons/vpn/peers/:id", "/api/v1/addons/vpn/status", "/api/v1/addons/vpn/config-string", "/api/v1/addons/vpn/qr" ], "skills": [ { "name": "vpn-read", "displayName": "VPN: Peers & Status lesen", "description": "Listet VPN-Peers (WireGuard/Tailscale) für den Nutzer mit Verbindungsstatus (connected/disconnected) und Peer-Status (Handshake/Transfer). Reiner Lesezugriff — legt nichts an.", "permissions": [ "addons/vpn/peers", "addons/vpn/status", "addons/vpn/config" ], "endpoint": "/api/v1/addons/vpn/peers", "scripts": [] }, { "name": "vpn-manage", "displayName": "VPN: Peers & Verbindung verwalten", "description": "Legt die BYOK-Verbindung zum VPN-Server an/entfernt diese und fügt Peers hinzu oder entfernt sie (per-User gebucht: provider, base URL, Token — niemals das Passwort im Klartext zurückgegeben). Stellt die WireGuard-Peer-Konfiguration und den Konfig-QR bereit.", "permissions": [ "addons/vpn/peers", "addons/vpn/config", "addons/vpn/config-string", "addons/vpn/qr" ], "endpoint": "/api/v1/addons/vpn/peers", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": null }, { "id": "websearch", "uuid": "c39538aa-2123-46d4-b973-b1ffc6b3b2e4", "name": "Research", "version": "2.1.3", "description": "Unified research capability: web search (Brave, ZAI, Google, SearXNG) for chat agents, plus trend radar, briefing studio, YouTube intelligence, web fetch (URL extraction), image analysis, and PDF analysis. Consolidates websearch + trend-radar + briefing-studio + youtube-intelligence + research-tools (ADR-008, issue #374).", "author": "Aiopta", "icon": "🧩", "capabilities": [ "search", "web-search", "multi-provider", "brave-search", "zai-search", "google-search", "searxng", "trend-scanning", "watchlists", "news-monitoring", "briefing-generation", "script-framing", "youtube-analysis", "transcript-analysis", "content-ideation", "title-patterns", "research", "web-fetch", "image-analysis", "pdf-analysis" ], "tags": [], "download": "/artifacts/websearch-2.1.3.zip", "sha256": "e6ef4bab2cfbaedc98cc5a6ac5d1b6babcd55b9d9ffcade422d8f5582636ce3b", "size": 187399, "page": { "path": "/addons/websearch", "name": "Research", "icon": "🔍", "section": "Tools", "component": "@addons/websearch/src/components/WebSearchSettings" }, "deprecated": false, "endpoints": [ "/api/v1/addons/websearch/search", "/api/v1/addons/websearch/zread", "/api/v1/addons/websearch/settings", "/api/v1/addons/websearch/status", "/api/v1/addons/websearch/providers", "/api/v1/addons/websearch/web-fetch", "/api/v1/addons/websearch/image-analysis", "/api/v1/addons/websearch/pdf-analysis", "/api/v1/addons/websearch/trend-radar/status", "/api/v1/addons/websearch/trend-radar/news", "/api/v1/addons/websearch/trend-radar/scan", "/api/v1/addons/websearch/trend-radar/watchlists", "/api/v1/addons/websearch/trend-radar/watchlists/:id/run", "/api/v1/addons/websearch/briefing-studio/status", "/api/v1/addons/websearch/briefing-studio/research", "/api/v1/addons/websearch/briefing-studio/script-frame", "/api/v1/addons/websearch/youtube-intelligence/status", "/api/v1/addons/websearch/youtube-intelligence/channel/analyze", "/api/v1/addons/websearch/youtube-intelligence/video/transcript", "/api/v1/addons/websearch/youtube-intelligence/patterns", "/api/v1/addons/websearch/youtube-intelligence/ideas" ], "skills": [], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "README aus
addon.json+ vorhandenen Routen generiert (scripts/generate-addon-readmes.js). Bei manuellen Ergänzungen den Generator-Hinweis entfernen.
Enable web search capabilities for chat agents with multi-provider support (Brave, ZAI, Google, SearXNG). Allows agents to search the web and read URLs for current information. Since issue #374 the addon also carries the consolidated research-tools capabilities: web fetch (URL content extraction), image analysis (ZAI Vision) and PDF analysis (ZAI PDF).
\nwebsearch/addons/websearchDieses Addon benötigt folgende Secrets/Provider-Konfiguration (Settings → Credentials bzw. Provider-Store, nie in addon.json):
\nBRAVE_API_KEYGOOGLE_SEARCH_API_KEYSEARXNG_API_KEYZAI_API_KEY| Methode(n) | Pfad |
|---|---|
| GET, POST | /api/v1/addons/websearch/config |
| GET | /api/v1/addons/websearch/providers |
| POST | /api/v1/addons/websearch/search |
| GET, POST | /api/v1/addons/websearch/settings |
| GET | /api/v1/addons/websearch/status |
| POST | /api/v1/addons/websearch/zread |
| GET | /api/v1/addons/websearch/web-fetch |
| POST | /api/v1/addons/websearch/image-analysis |
| POST | /api/v1/addons/websearch/pdf-analysis |
GET /api/v1/addons/websearch/web-fetch?url=<url>Authentifiziert. Liefert { success, url, title, content, extractedAt }. Der Abruf läuft
hinter einem SSRF-Guard (nur http/https, DNS-geprüfte öffentliche Adressen, Redirect-Hops
werden einzeln re-validiert, Größen-/Zeitlimit) — private/loopback/link-local/metadata-Ziele
werden mit 403 abgelehnt, ohne dass ein ausgehender Request stattfindet. Siehesrc/lib/research-tools/web-fetch.ts und addons/research-tools/SUNSET.md.
POST /api/v1/addons/websearch/image-analysis\nBody: { "imagePath": "uploads/image.jpg", "prompt": "Describe this image" }POST /api/v1/addons/websearch/pdf-analysis
Body: { "pdfPath": "docs/file.pdf", "prompt": "Summarize this document" }
```
\nPer-User-Isolation (#147 / ADR-054, 1:1 aus research-tools übernommen): beide
Endpoints sind authentifiziert und lesen ausschließlich Dateien unter dem per-User-Datenroot
(
<DATA_DIR>/addons/websearch/<userId>).imagePath/pdfPathsind relativ zu diesemRoot — absolute Pfade und
../-Traversal werden mit403abgelehnt.
Two admin capabilities for resellers/operators (ADR-027):
\n- White-label branding — rebrand this Aiopta instance (app name, logo URL, accent color,
login tagline, "powered by Aiopta" toggle), applied across the shell + login. **SAFE
DEFAULTS**: an unconfigured instance is visually identical to stock Aiopta.
- Business-packs — named bundles { addons[], agentTemplates[], settings } that set up a business
vertical in a few clicks by reusing existing primitives — enable + instantiate. Apply is **safe +
idempotent** (re-apply never duplicates).
- Full white-label (#121 / INBOX-52) — logo upload + asset-hosting, a tier-gated branding
entitlement (built on the #119 licensing scaffold), and per-customer custom-domain config. See
"Full white-label" below.
It extends + orchestrates — it never forks a store or reimplements install/provisioning.
\n- Branding = { appName, logoUrl, accentColor, loginTagline, poweredBy } lives in core app_settings
via src/lib/branding.ts — a sibling of provisioning.ts (ADR-020) that SHARES INSTANCE_NAME +
INSTANCE_BRAND_COLOR and adds BRANDING_LOGO_URL/_LOGIN_TAGLINE/_POWERED_BY. No new table.
- getBranding() returns the exact current MC values when unset (AIOPTA_DEFAULT_BRANDING, accent
#7c3aed). setBranding() is an allow-list + shape-validates color (hex) and logo (empty /
/… / http(s); javascript:/data:/protocol-relative rejected).
- The shell + login read the public GET /api/v1/branding; a core BrandingProvider
(src/lib/branding-client.tsx, in app/layout.tsx) renders defaults immediately then threads a custom
accent through var(--color-accent*) via a CSS variable on <html> — no per-component edits.
- BusinessPack = { id, name, description, vertical, addons[], agentTemplates[], settings{} }.
- 3 built-ins (repo-bundled addons + seeded templates): ecommerce, agency-leadgen, content-saas.
- Apply reuses primitives and is idempotent: addons → enabled via the shared extensions table
(Addon-Manager, ADR-022; already-enabled → skipped); templates → instantiated for the caller via the
Phase-A route (own key, no secrets; owned template / 409 → skipped); settings → allow-listed keys only.
- Apply-state is derived from extensions + user_agents (the addon owns no table).
- Logo upload + asset-hosting (OD #35) — src/lib/logo-storage.ts stores an uploaded image
registry-free under DATA_DIR/white-label/ (a JSON sidecar — no table). The format is determined
by magic-byte sniffing (PNG/JPEG/GIF/WEBP/SVG); the client MIME is never trusted, and a 2 MiB
cap applies. PUT …/logo accepts a multipart file or JSON { dataUrl | base64 }; the public
GET …/logo serves the bytes (with X-Content-Type-Options: nosniff + a strict CSP so an uploaded SVG
stays inert), and the root-relative serve path is written into the core Branding.logoUrl (which the
existing isValidLogoUrl already accepts — no core change). DELETE …/logo resets to the default.
- Branding entitlement, tier-gated (OD #36, builds on #119/ADR-050) — src/lib/branding-entitlement.ts
is a read-only consumer of src/lib/entitlements.ts (hasEntitlement) + src/lib/tier-config.ts
(TIER_REGISTRY); neither is modified. The shipped Feature union has no dedicated whiteLabel
flag yet, so it maps to the closest existing one, addons.private-registry (enterprise-only) — one line
in BRANDING_FEATURE to change later. A non-entitled tier gets a graceful 402 on the logo/domain
writes (branding falls back to the Aiopta default, with an "upgrade" hint) — never a crash.
- Custom-domain config (OD #34) — src/lib/custom-domain.ts stores a hostname + status
(unconfigured/pending/active) + a note as a JSON blob in app_settings (registry-free, `getDb()
.prepare().run()`). Actual TLS certs + DNS are owner/infra at the reverse-proxy — no cert code ships.
An unconfigured instance uses the default domain (the public URL stays owned by the existing ingress).
- Admin-gated: branding by user.manage, pack apply by addon.manage (requireCapability).
- No secrets: branding is public-by-nature; pack apply mints a new own key via the Phase-A route and
copies no secret.
- No external calls: pack apply dispatches over the same-origin Aiopta API (assertSameOrigin); no
container, no outbound request (ADR-009).
- Safe defaults: zero visual change when unconfigured.
Dual-registered in addon.json + src/manifest.ts (plus the core public read):
GET /api/v1/branding (core, public — shell/login read this)GET /api/v1/addons/white-label/branding · PUT /api/v1/addons/white-label/branding (user.manage)GET /api/v1/addons/white-label/packs (addon.manage)POST /api/v1/addons/white-label/packs/[id]/apply (addon.manage)GET /api/v1/addons/white-label/status · GET /api/v1/addons/white-label/widget (user.manage)GET /api/v1/addons/white-label/logo (public serve) · PUT · DELETE (user.manage, entitlement-gated write)GET /api/v1/addons/white-label/config (user.manage) · PUT (user.manage, entitlement-gated)See SKILL.md for the agent-facing cheat-sheet and ADR-027 (white-label business
packs, in the core repo under docs/architecture/) for the full decision. **Logo upload, tier-gated branding entitlement, and custom-domain config are now
built (OD #34/#35/#36).** Still owner/infra: actual TLS cert issuance + DNS (handled at the reverse-proxy,
OD #34), and a dedicated whiteLabel tier-feature flag (additive in #119 — today mapped toaddons.private-registry).
Create and manage WordPress sites and WooCommerce shops from inside Aiopta —
pages, posts, themes, menus (WordPress) and products, orders, coupons, customers (WooCommerce) —
usable both by agents (via the addon API) and by humans (via the management page).
The addon works in two modes, chosen on the management page and persisted in Aiopta addon-config
(WORDPRESS_MODE, default container):
- Aiopta-Container hochfahren (container, default) — the Aiopta-managed WordPress + WooCommerce
container (ADR-010). Full container self-provisioning is still pending (TODO #133); until then
the status reports "Container nicht provisioniert".
- Bestehende Seite verbinden (external) — the owner connects an existing WordPress +
WooCommerce site. They enter the site URL, a WordPress application password (user +
app-password) and the WooCommerce consumer key + secret, hit "Verbindung testen", and
then every WP/Woo call runs against that real site. This mode is fully functional today.
src/lib/wp-client.ts resolves the base URL via resolveBaseUrl(): in external mode it is the
owner's WORDPRESS_SITE_URL; in container mode it is getContainerAddonInternalUrl("wordpress").
Either way there is no hard-coded localhost/host anywhere — when no base URL is resolvable the
client throws a clear, mode-aware "not configured / not provisioned" error.
- The container path is a container, not a host. WordPress with the WooCommerce plugin is an
external tool, so it is declared as a container in addon.json / manifest.ts
(registry.langkau.info/aiopta/wordpress-woo:latest, internalPort 80,
healthPath /wp-json/). It is booted at install by the container-service, started/stopped by the
enable/disable lifecycle (G6), and removed on uninstall. The addon writes no lifecycle code.
- Reached only via the resolved base URL. src/lib/wp-client.ts talks to the
WordPress REST API (/wp-json/wp/v2/...) and WooCommerce REST API (/wp-json/wc/v3/...)
using the mode-aware base URL above.
- Secrets via Aiopta-config, never the manifest. The manifest declares only the names of the
config keys (envSchema). Values — the WordPress application password and the WooCommerce
consumer key + secret — are stored in Aiopta addon-config (setAddonConfiguration, secret-looking
keys flagged is_secret = 1). The masked GET /config response only reports whether each
secret is set, never its value. No secret value is ever written into the manifest or logged.
| Surface | Mechanism | Config keys (Aiopta addon-config / envSchema) |
|---------|-----------|---------------------------------------------|
| Mode + site URL | non-secret connection config | WORDPRESS_MODE (container\\|external), WORDPRESS_SITE_URL |
| WordPress core (/wp-json/wp/v2) | Application password (Basic auth) | AIOPTA_WP_USER, AIOPTA_WP_APP_PASSWORD |
| WooCommerce (/wp-json/wc/v3) | Consumer key + secret (Basic auth) | AIOPTA_WC_CONSUMER_KEY, AIOPTA_WC_CONSUMER_SECRET |
| Container / DB | non-secret connection config | WORDPRESS_DB_HOST, WORDPRESS_DB_NAME, WORDPRESS_DB_USER, WORDPRESS_TABLE_PREFIX |
All routes are namespaced under /api/v1/addons/wordpress/ and require auth.
GET /status → mode + reachability + connection + config status\nGET /config PUT /config → read (masked) / save mode + connect-existing creds\nPOST /test → "Verbindung testen": probe WP + Woo on the configured site\nGET /sites POST /sites → list / create managed site(s)\nGET /pages POST /pages → list / create pages { "title", "content?", "status?" }\nGET /posts POST /posts → list / create posts { "title", "content?", "status?" }\nGET /themes POST /themes → list / activate theme { "stylesheet" }\nGET /menus POST /menus → list / create menu { "name" }GET /products POST /products → list / create product { "name", "regular_price?", ... }\nGET /products/[id] PUT /products/[id] DELETE /products/[id]\nGET /orders → list orders (?status=, ?per_page=)\nGET /orders/[id] PUT /orders/[id] → fetch / update an order (e.g. status)\nGET /coupons POST /coupons → list / create coupon { "code", "amount?", "discount_type?" }\nGET /customers → list customersResponses use the { "success": true, "data": … } envelope. On failure read error and the HTTP
status (a 503 means the container is not provisioned; a 400 means credentials are not set).
addons/wordpress/\n├── addon.json # Manifest (page + widget + container + endpoints)\n├── README.md\n├── SKILL.md # Agent skill\n├── src/\n│ ├── manifest.ts # Extension (dual-registration: routes + page + container)\n│ ├── page.tsx # Management UI (Sites/Pages/Posts + Products/Orders/Coupons)\n│ ├── widget.tsx # Dashboard status widget (declarative key-values)\n│ ├── lib/wp-client.ts # WP + Woo REST client — mode-aware base URL (external site OR container) + Aiopta-config\n│ └── app/api/v1/addons/wordpress/{status,config,test,sites,pages,posts,themes,menus,products,products/[id],orders,orders/[id],coupons,customers}/route.ts\n└── tests/unit/ # manifest validity + wp-client logic (dual-mode + testConnection) + config/test routes (mocked)External mode works today — the owner connects an existing site (URL + app-password + Woo
keys), tests it, and uses the full CRUD surface immediately.
The container path needs its image + self-provisioning before it is usable:
\n\nTODO(#133): container self-provisioning — the
containermode declares the manifest
containerblock but cannot yet actually provision/boot the WP+Woo stack from inside the addon.Tracked as #133 (
addons/wordpressis a concrete instance of #123/#133). Until thencontainermode reports "Container nicht provisioniert"; use
externalmode to connect an existing site.TODO(owner):
wordpress-woo-image— build + publish the
registry.langkau.info/aiopta/wordpress-wooimage (WordPress + WooCommerce behind itsHTTP server, exposing
/wp-json/).TODO(owner): credentials — for either mode, the WordPress application password
(
AIOPTA_WP_USER/AIOPTA_WP_APP_PASSWORD) and the WooCommerce consumer key + secret(
AIOPTA_WC_CONSUMER_KEY/AIOPTA_WC_CONSUMER_SECRET) are stored in Aiopta addon-config (via the addon pageor
PUT /config). No secret is committed. The VALUES are owner-secret; the addon builds themechanism/UI.
MIT
", "byteSize": 7176 } } }, { "id": "workflow-builder", "uuid": "83b7fda8-ea5c-4a92-a98f-60887f0936ed", "name": "Workflow / Automation Builder", "version": "1.1.11", "description": "Define automations (a trigger + ordered steps) that Aiopta runs server-side — an n8n-lite scoped to this platform. Triggers: manual, schedule (interval), webhook (tokened inbound URL), event. Step types: http (same-origin Aiopta API call), agent (run an Aiopta agent via the gateway), condition, delay. Steps thread prior-step output via {{stepN.field}}; the engine enforces a same-origin allow-list (never external services, never eval) and persists run history. No container (ADR-024). Canonical home of the former integrations addon's trigger surface (issue #375): the per-user webhook-trigger registry (/webhooks) and the admin-gated schedule-trigger view (/cron) live here.", "author": "Aiopta", "icon": "🧩", "capabilities": [ "workflow-definitions", "workflow-execution", "workflow-triggers", "workflow-run-history", "workflow-webhooks", "webhooks", "cron", "integrations" ], "tags": [ "onboarding" ], "download": "/artifacts/workflow-builder-1.1.11.zip", "sha256": "dd16d83a70942e5b5fdd2d0e2cc51bc47cc1d2ead0359ab82a0fb26a783c0518", "size": 292447, "page": { "id": "workflow-builder-page", "path": "/addons/workflow-builder", "name": "Workflow Builder", "icon": "🔀", "section": "Automation", "component": "@addons/workflow-builder/src/page" }, "deprecated": false, "endpoints": [ "/api/v1/addons/workflow-builder/status", "/api/v1/addons/workflow-builder/webhooks", "/api/v1/addons/workflow-builder/cron", "/api/v1/addons/workflow-builder/workflows", "/api/v1/addons/workflow-builder/workflows/:id", "/api/v1/addons/workflow-builder/workflows/:id/run", "/api/v1/addons/workflow-builder/workflows/:id/runs", "/api/v1/addons/workflow-builder/workflows/:id/webhook", "/api/v1/addons/workflow-builder/widget", "/api/v1/addons/workflow-builder/widget-runs", "/api/v1/addons/workflow-builder/widget-link" ], "skills": [ { "name": "workflow-manage", "displayName": "Workflow: Define & manage automations", "description": "List/create/edit/delete workflows (trigger + ordered steps). Validates the trigger and every step shape; a webhook trigger gets a server-minted token. Pure CRUD — does not execute anything.", "permissions": [ "addons/workflow-builder/workflows", "addons/workflow-builder/status" ], "endpoint": "/api/v1/addons/workflow-builder/workflows", "scripts": [] }, { "name": "workflow-run", "displayName": "Workflow: Run & inspect history", "description": "Execute a workflow now (manual trigger) and read its run history. The engine orchestrates ONLY the Aiopta API (same-origin allow-list) and Aiopta agents via the gateway — never external services, never eval. The caller's auth is forwarded to internal steps so RBAC still applies.", "permissions": [ "addons/workflow-builder/workflows", "addons/workflow-builder/status" ], "endpoint": "/api/v1/addons/workflow-builder/workflows/:id/run", "scripts": [] } ], "mcpServers": [], "pricing": null, "pricingTiers": { "schemaVersion": 1, "currency": null, "tiers": [ { "id": "free", "name": "Free", "priceMinor": 0, "interval": null, "features": [], "contactOnly": false } ] }, "meta": { "readme": { "filename": "README.md", "sourcePath": "README.md", "rendered": "An in-Aiopta automation builder — a Zapier/n8n-lite scoped to this platform. A workflow is
a trigger plus an ordered list of steps that Aiopta runs server-side, threading each
step's output into the next via {{stepN.field}} interpolation.
It orchestrates existing Aiopta capabilities and never calls external services directly (ADR-009):http steps hit only the Aiopta API (same-origin allow-list), agent steps go through the Aiopta gateway.
- Workflow = { id, name, enabled, trigger, steps[] }.
- Trigger ∈ manual · schedule (interval seconds) · webhook (per-workflow token) · event (Aiopta
event name).
- Step = { id, type, name?, config, onError }, type ∈:
- http — an Aiopta-internal API call (method + same-origin /api/... path + optional body).
- agent — run an Aiopta agent via the gateway with a prompt (built from prior step output).
- condition — left <op> right; on false the run stops cleanly (skip-rest). No eval.
- delay — wait ms (capped at 60s).
integrations (issue #375)Workflow-builder is the canonical home of the former integrations addon's two
endpoints (parent #312, cluster automation-orchestration,docs/ADDON-CLUSTERS.md):
- /webhooks (GET/POST/DELETE) — the per-user webhook-trigger registry
(register/list/delete webhook entries; user_id-scoped, secrets masked).
Auth: userRoute — 401 without a session; every read/write is isolated to
the caller (#139).
- /cron (GET) — the read-only schedule-trigger view over the
instance scheduler config (<DATA_DIR>/cron/jobs.json). Auth: adminRoute
— 401 unauthenticated / 403 non-admin (#586, ADR-054); only schedule
metadata is exposed, never a job payload/secret.
The legacy /api/v1/addons/integrations/* routes stay alive as alias shims
during the sunset window (until 2026-12-31, RFC 8594 headers) and answer
410 Gone afterwards — see addons/integrations/README.md for the mapping
and the rollback recipe. The data migration is zero-copy: the webhooks table
and jobs.json are unchanged; only the serving endpoints moved.
- Same-origin allow-list: an http step's path must begin with /api/ and resolve to the Aiopta
origin; absolute/protocol-relative/traversal paths are refused both at validation time and at request
time in the engine. A workflow can never make an arbitrary outbound request.
- No eval / no code execution: conditions are a fixed operator switch; interpolation is plain string
substitution.
- Auth forwarding: manual runs forward the caller's session/agent auth to internal steps, so Aiopta
RBAC still applies — a workflow can do no more than its initiator.
- Webhook: token-gated (constant-time compare), no Aiopta session; the token is never logged or echoed.
Two addon-owned tables (created in install(), dropped in uninstall() via Aiopta core's getDb()):workflow_builder_workflows and workflow_builder_runs (run history). The addon never touches the core
schema. The webhook-trigger registry (/webhooks, #375) reads/writes the core-owned webhooks
table through the user-scope layer (scopedStore), exactly as its integrations predecessor did.
A workflow list + a structured step editor: pick a trigger, add/reorder/remove steps with
type-specific config, Run now, and a run-history timeline. A full visual drag-drop canvas is a
future enhancement (see docs/OPEN-DECISIONS.md).
See SKILL.md for the agent-facing endpoint cheat-sheet and docs/architecture/ADR-024-workflow-builder.md
for the design.