oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/kb/subsystems/action-approval-model.md
oskar a427aad47e feat(kb): przenosiny type=subsystem do kb/subsystems/ (18 plikow, bez SPLIT) 
public (wzorce/schematy, bez IP/portow/sciezek hostow): observer,
capability-model, event-system, standards, agent-operating-procedures,
service-model, action-approval-model.

private: recon-multiagent, fleet-inventory, fleet-inventory-verify,
kb-mail-pillar, kb-documents-pillar, topology, agent-system.

deprecated (martwe stuby z 2026-04-15) — visibility private wg
rozstrzygniecia 6: access-model, core-stack, legacy-services-list, networking.

git mv + frontmatter, tresc nietknieta.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 16:19:30 +02:00

2.1 KiB
Raw Blame History

okf type visibility status updated links
0.1 subsystem public active 2026-05-20

Action Approval Data Model

Actions are JSON files stored in /opt/homelab/actions/{status}/{action_id}.json.

Statuses

  • pending: Waiting for operator approval. AI agents create actions in this state.
  • approved: Approved by operator, ready for execution.
  • rejected: Rejected by operator, will not be executed.
  • running: Currently being executed by an agent (e.g. materializer).
  • completed: Successfully executed.
  • failed: Execution failed.

Human-in-the-Loop (HIL) Protocol

  1. Request: Agent identifies a required change and writes a JSON to actions/pending/.
  2. Notification: System notifies the human operator.
  3. Audit: Human reviews details.reason and details.diff.
  4. Authorization: Human moves file to approved/.
  5. Execution: Agent monitors approved/ and executes the task.

Schema

{
  "action_id": "string",
  "service": "string",
  "node": "string",
  "type": "deploy_service | restart_service | rollback | scale",
  "risk": "nominal | guarded | critical",
  "status": "pending | approved | rejected | ...",
  "created_at": <unix_seconds>,
  "updated_at": <unix_seconds>,
  "details": {
    "image": "string",
    "reason": "string",
    "diff": "string"
  },
  "transition_history": [
    {
      "from": "string | null",
      "to": "string",
      "timestamp": <unix_seconds>,
      "by": "string (system | operator-tg-12345 | webui)"
    }
  ]
}

Workflow

  1. A system component (e.g. runtime-materializer or a future analyzer) creates a file in actions/pending/.
  2. telegram-bot detects the file, sends a message to allowed users.
  3. Operator clicks "Approve" or "Reject".
  4. telegram-bot moves the file to actions/approved/ or actions/rejected/ atomically, appending a transition to transition_history.
  5. The responsible agent (e.g. stability-agent on the target node) picks up the approved action, moves it to running, executes it, and finally moves it to completed or failed.