FTMahringer/Synapse

Fork 0

Human Approval, Review Gates and Multi-User Governance Workflows #50

New issue

Open

opened 2026-05-24 03:10:49 +02:00 by FTMahringer · 1 comment

FTMahringer commented

2026-05-24 03:10:49 +02:00

(Migrated from github.com)

Problem / Motivation

AI systems are powerful, but still imperfect.

Synapse workflows, agents and automation systems should not always execute actions automatically without human oversight.

This becomes especially important once Synapse supports:

infrastructure actions
shell execution
workflow automation
plugin installation
deployment actions
external integrations
multi-user/team environments

Human approval and review workflows should become a first-class concept inside Synapse.

Related issues:

#35 Workflow & Automation Ideas
#38 Plugin API & Ecosystem Architecture Refactor for Long-Term Extensibility
#42 External Account Login & Developer Identity Linking
#43 External Worker Runtime for Non-Java Plugins
#45 ECHO Local Debugger & Observability Architecture

Proposed Solution

Introduce approval/review gates for workflows, AI actions and infrastructure operations.

Possible workflow:

AI wants to execute action
 → approval policy triggers
 → request enters review queue
 → user/team reviews request
 → approved or denied
 → action executes or stops

Possible approval targets:

shell execution
infrastructure changes
plugin installation
plugin updates
workflow publishing
workflow execution
secret access
external API actions
deployment actions
dangerous automation tasks

Multi-User & Team Architecture

Synapse is planned as a multi-user platform.

Possible user system:

Admin (max 1)
Moderator
User
User Teams

Optional external integrations:

GitLab
Forgejo/Gitea
GitHub
OIDC providers
self-hosted identity systems

Possible future team features:

approval groups
shared workflows
shared plugin access
team-scoped permissions
organization-level policies
internal plugin stores

Git-Based Review Inspiration

Potential inspirations:

GitHub Pull Requests
GitLab Merge Requests
GitHub Actions approvals
CI/CD deployment gates

Possible examples:

Workflow Update
 → pending review
 → moderator approval required
 → merged/published

AI requests infrastructure action
 → operator approval required
 → execution allowed

Approval Policies

Possible policies:

approvalPolicies:
  - action: shell.execute
    requireApproval: true

  - action: plugin.install.community
    requireModeratorApproval: true

  - action: proxmox.vm.delete
    requireAdminApproval: true

Future Ideas

approval expiration
staged approvals
multi-review approvals
emergency override mode
AI-generated approval summaries
audit timeline integration
approval history replay in ECHO
workflow publishing review queues
team-based plugin governance

Security Requirements

all approvals should be audited
denied actions should be logged
approval permissions must respect roles
approval spoofing protections
local-only environments should work without external auth providers
external identity providers should remain optional

Priority

High / Strategic

Human approval and governance will likely become essential once Synapse manages infrastructure, workflows and multi-user automation.

## Problem / Motivation AI systems are powerful, but still imperfect. Synapse workflows, agents and automation systems should not always execute actions automatically without human oversight. This becomes especially important once Synapse supports: - infrastructure actions - shell execution - workflow automation - plugin installation - deployment actions - external integrations - multi-user/team environments Human approval and review workflows should become a first-class concept inside Synapse. Related issues: - #35 Workflow & Automation Ideas - #38 Plugin API & Ecosystem Architecture Refactor for Long-Term Extensibility - #42 External Account Login & Developer Identity Linking - #43 External Worker Runtime for Non-Java Plugins - #45 ECHO Local Debugger & Observability Architecture --- ## Proposed Solution Introduce approval/review gates for workflows, AI actions and infrastructure operations. Possible workflow: ```text AI wants to execute action → approval policy triggers → request enters review queue → user/team reviews request → approved or denied → action executes or stops ``` Possible approval targets: - shell execution - infrastructure changes - plugin installation - plugin updates - workflow publishing - workflow execution - secret access - external API actions - deployment actions - dangerous automation tasks --- ## Multi-User & Team Architecture Synapse is planned as a multi-user platform. Possible user system: ```text Admin (max 1) Moderator User User Teams ``` Optional external integrations: - GitLab - Forgejo/Gitea - GitHub - OIDC providers - self-hosted identity systems Possible future team features: - approval groups - shared workflows - shared plugin access - team-scoped permissions - organization-level policies - internal plugin stores --- ## Git-Based Review Inspiration Potential inspirations: - GitHub Pull Requests - GitLab Merge Requests - GitHub Actions approvals - CI/CD deployment gates Possible examples: ```text Workflow Update → pending review → moderator approval required → merged/published ``` ```text AI requests infrastructure action → operator approval required → execution allowed ``` --- ## Approval Policies Possible policies: ```yaml approvalPolicies: - action: shell.execute requireApproval: true - action: plugin.install.community requireModeratorApproval: true - action: proxmox.vm.delete requireAdminApproval: true ``` --- ## Future Ideas - approval expiration - staged approvals - multi-review approvals - emergency override mode - AI-generated approval summaries - audit timeline integration - approval history replay in ECHO - workflow publishing review queues - team-based plugin governance --- ## Security Requirements - all approvals should be audited - denied actions should be logged - approval permissions must respect roles - approval spoofing protections - local-only environments should work without external auth providers - external identity providers should remain optional --- ## Priority High / Strategic Human approval and governance will likely become essential once Synapse manages infrastructure, workflows and multi-user automation.

jshaofa-ui commented

2026-05-24 12:18:46 +02:00

(Migrated from github.com)

Solution: Human Approval Workflows

I've developed a comprehensive approval workflow system that integrates with Synapse's existing plugin and agent architecture.

Key Design Decisions

Opt-in by default — Actions auto-approved unless explicitly gated by policy
Granular policies — Per-category, per-risk-level, per-environment rules
Multi-channel approval — Web UI, CLI, API, webhook callbacks
Timeout handling — Auto-approve or auto-reject after configurable timeout
Audit trail — Every decision logged with actor, channel, and timestamp

Architecture

backend/approval/ — Core models, policy engine, queue management
backend/agents/approval_mixin.py — Drop-in mixin for any agent
backend/api/routes/approval.py — REST API endpoints
frontend/src/pages/approvals/ — Approval dashboard UI
plugins/approval-plugin/ — Configurable policy plugin

Default Policies

Shell execution: Always requires approval (any risk level)
Deployments: Require approval for medium+ risk
Plugin installs: Require approval (any risk level)

Estimated Effort: ~7 days

Full solution document available. Integrates with existing Synapse plugin system.

## Solution: Human Approval Workflows I've developed a comprehensive approval workflow system that integrates with Synapse's existing plugin and agent architecture. ### Key Design Decisions 1. **Opt-in by default** — Actions auto-approved unless explicitly gated by policy 2. **Granular policies** — Per-category, per-risk-level, per-environment rules 3. **Multi-channel approval** — Web UI, CLI, API, webhook callbacks 4. **Timeout handling** — Auto-approve or auto-reject after configurable timeout 5. **Audit trail** — Every decision logged with actor, channel, and timestamp ### Architecture - `backend/approval/` — Core models, policy engine, queue management - `backend/agents/approval_mixin.py` — Drop-in mixin for any agent - `backend/api/routes/approval.py` — REST API endpoints - `frontend/src/pages/approvals/` — Approval dashboard UI - `plugins/approval-plugin/` — Configurable policy plugin ### Default Policies - Shell execution: Always requires approval (any risk level) - Deployments: Require approval for medium+ risk - Plugin installs: Require approval (any risk level) ### Estimated Effort: ~7 days Full solution document available. Integrates with existing Synapse plugin system.