Runbooks and Skills

Skills run registry tools in sequence. Runbooks also run registry tools, and add approval flags, failure handling, and rollback steps.

A human approval gate is not a permission override. The tool still has to be at or below ai.max_permission.

Built-in skills

The daemon loads five general skills and four reasoning skills. The general skills arehealth-check, deployment-analysis, log-investigation,cost-optimizer, and diagnose-microvm-cold-start. The reasoning skills are investigate_incident, analyze_logs,correlate_events, and suggest_fix.

Skills execute their steps directly and have no approval gate. A step that fails withcontinue_on_error = false ends the skill with SkillFailed.

Built-in runbooks

RunbookMain step tool ids
disk-cleanupquery_metrics, query_logs, query_metrics
restart-loop-detectionquery_logs, query_metrics, list_alerts
certificate-expiry-renewalquery_metrics, rotate_certs, query_metrics
microvm-cold-start-recoverymicrovm_status, microvm_rebuild, microvm_warm,query_metrics

The disk-cleanup step named "Rotate Application Logs" callsquery_logs; it does not rotate or delete logs.

Approval gates

Only a runbook step marked ApprovalType::Required waits for a human. Three built-in steps have that marking: rotate-logs indisk-cleanup, renew-cert incertificate-expiry-renewal, and rebuild-snapshot inmicrovm-cold-start-recovery.

The engine creates a token, emits StepAwaitingApproval, and blocks on aoneshot channel.

The TUI shows the prompt. Pressing y or n callsApproveRunbookStep, which calls RunbookEngine::approve with the token.

A rejection marks the step skipped and fails the runbook without running rollback steps.

An approved step still passes through the tool registry's permission check. Atread, an approved Safe, Mutate, orFull tool is denied.

Failure and rollback

When a runbook step fails and continue_on_error is false, the engine runs everyrollback_steps entry before it emits RunbookFailed.

Rollback is best effort. The engine emits RollbackStarted, ignores each rollback tool error, and reports that rollback ran.

A rejected approval is the exception: the engine skips the step and reportsrollback_executed: false.

MicroVM ceiling

diagnose-microvm-cold-start needs safe, because its first tool ismicrovm_status at Safe and that step stops on error. Atread, the skill fails at microvm_status withPermissionDenied.

microvm-cold-start-recovery needs safe to pass its first status step, but it needs mutate for recovery. microvm_rebuild isMutate and requires approval, while microvm_warm isMutate with no approval gate.

At read, the runbook fails at the status step and runs its rollback step. Atsafe, an approved rebuild is still denied and causes rollback, and warm would also be denied if reached. Full recovery requires mutate.

Where to see it

Select ai-ops in the TUI left rail. The execution panel shows tool steps and any pending approval prompt.