Skip to content

05-permissions-and-approval-workflow.md

Latest commit

 

History

History
247 lines (182 loc) · 7.91 KB

05-permissions-and-approval-workflow.md

File metadata and controls

247 lines (182 loc) · 7.91 KB
layout default
title Chapter 5: Permissions and Approval Workflow
nav_order 5
parent HAPI Tutorial

Chapter 5: Permissions and Approval Workflow

Welcome to Chapter 5: Permissions and Approval Workflow. In this part of HAPI Tutorial: Remote Control for Local AI Coding Sessions, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

Remote approvals are the core safety boundary when agents request actions.

Approval Event Flow

  1. agent emits permission request
  2. CLI forwards request to hub
  3. hub stores and broadcasts to PWA/Telegram
  4. operator approves/denies
  5. decision returns to active session

Policy Matrix

Request Type Recommended Policy
scoped file edits approve with diff visibility
command execution require explicit command preview
destructive/system-wide actions deny by default

Operational Controls

  • enforce timeout for unresolved approvals
  • require request metadata (target file/command/context)
  • retain immutable approval logs for audit and incident review

Summary

You now have a governance model for remote permission handling in HAPI.

Next: Chapter 6: PWA, Telegram, and Extensions

What Problem Does This Solve?

Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for core abstractions in this chapter so behavior stays predictable as complexity grows.

In practical terms, this chapter helps you avoid three common failures:

  • coupling core logic too tightly to one implementation path
  • missing the handoff boundaries between setup, execution, and validation
  • shipping changes without clear rollback or observability strategy

After working through this chapter, you should be able to reason about Chapter 5: Permissions and Approval Workflow as an operating subsystem inside HAPI Tutorial: Remote Control for Local AI Coding Sessions, with explicit contracts for inputs, state transitions, and outputs.

Use the implementation notes around execution and reliability details as your checklist when adapting these patterns to your own repository.

How it Works Under the Hood

Under the hood, Chapter 5: Permissions and Approval Workflow usually follows a repeatable control path:

  1. Context bootstrap: initialize runtime config and prerequisites for core component.
  2. Input normalization: shape incoming data so execution layer receives stable contracts.
  3. Core execution: run the main logic branch and propagate intermediate state through state model.
  4. Policy and safety checks: enforce limits, auth scopes, and failure boundaries.
  5. Output composition: return canonical result payloads for downstream consumers.
  6. Operational telemetry: emit logs/metrics needed for debugging and performance tuning.

When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.

Source Walkthrough

Use the following upstream sources to verify implementation details while reading this chapter:

  • HAPI Repository Why it matters: authoritative reference on HAPI Repository (github.com).
  • HAPI Releases Why it matters: authoritative reference on HAPI Releases (github.com).
  • HAPI Docs Why it matters: authoritative reference on HAPI Docs (hapi.run).

Chapter Connections

Depth Expansion Playbook

Source Code Walkthrough

web/src/router.tsx

The Register interface in web/src/router.tsx handles a key part of this chapter's functionality:

declare module '@tanstack/react-router' {
    interface Register {
        router: AppRouter
    }
}

This interface is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.

hub/src/index.ts

The formatSource function in hub/src/index.ts handles a key part of this chapter's functionality:

/** Format config source for logging */
function formatSource(source: ConfigSource | 'generated'): string {
    switch (source) {
        case 'env':
            return 'environment'
        case 'file':
            return 'settings.json'
        case 'default':
            return 'default'
        case 'generated':
            return 'generated'
    }
}

type RelayFlagSource = 'default' | '--relay' | '--no-relay'

function resolveRelayFlag(args: string[]): { enabled: boolean; source: RelayFlagSource } {
    let enabled = false
    let source: RelayFlagSource = 'default'

    for (const arg of args) {
        if (arg === '--relay') {
            enabled = true
            source = '--relay'
        } else if (arg === '--no-relay') {
            enabled = false
            source = '--no-relay'
        }
    }

    return { enabled, source }

This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.

hub/src/index.ts

The resolveRelayFlag function in hub/src/index.ts handles a key part of this chapter's functionality:

type RelayFlagSource = 'default' | '--relay' | '--no-relay'

function resolveRelayFlag(args: string[]): { enabled: boolean; source: RelayFlagSource } {
    let enabled = false
    let source: RelayFlagSource = 'default'

    for (const arg of args) {
        if (arg === '--relay') {
            enabled = true
            source = '--relay'
        } else if (arg === '--no-relay') {
            enabled = false
            source = '--no-relay'
        }
    }

    return { enabled, source }
}

function normalizeOrigin(value: string): string {
    const trimmed = value.trim()
    if (!trimmed) {
        return ''
    }
    try {
        return new URL(trimmed).origin
    } catch {
        return trimmed
    }
}

function normalizeOrigins(origins: string[]): string[] {

This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.

hub/src/index.ts

The normalizeOrigin function in hub/src/index.ts handles a key part of this chapter's functionality:

}

function normalizeOrigin(value: string): string {
    const trimmed = value.trim()
    if (!trimmed) {
        return ''
    }
    try {
        return new URL(trimmed).origin
    } catch {
        return trimmed
    }
}

function normalizeOrigins(origins: string[]): string[] {
    const normalized = origins
        .map(normalizeOrigin)
        .filter(Boolean)
    if (normalized.includes('*')) {
        return ['*']
    }
    return Array.from(new Set(normalized))
}

function mergeCorsOrigins(base: string[], extra: string[]): string[] {
    if (base.includes('*') || extra.includes('*')) {
        return ['*']
    }
    const merged = new Set<string>()
    for (const origin of base) {
        merged.add(origin)
    }

This function is important because it defines how HAPI Tutorial: Remote Control for Local AI Coding Sessions implements the patterns covered in this chapter.

How These Components Connect

flowchart TD
    A[Register]
    B[formatSource]
    C[resolveRelayFlag]
    D[normalizeOrigin]
    E[normalizeOrigins]
    A --> B
    B --> C
    C --> D
    D --> E
Loading