The Modular, Self-Hosted Agentic Operating System

Basal Ganglia - Task Orchestrator

The Basal Ganglia is SanctumOS's action-selection and supervision system for long-running sub-agents. It serves as the system's action gate and habit engine for spawned tasks.

Overview

The Basal Ganglia (BG) is responsible for selecting one job, specifying its process and success criteria, and driving it to completion while suppressing competing work. It acts as the system's action gate and habit engine for spawned tasks.

Purpose

The Basal Ganglia selects one job, specifies its process and success criteria, and drives it to completion (pass/fail) while suppressing competing work. BG is the system's action gate and habit engine for spawned tasks.

Biological Inspiration

The Basal Ganglia in the human brain:

  • Cortex proposes many actions → BG gates one (Go), inhibits others (No-Go)
  • Can stop abruptly (hyperdirect pathway)
  • Learns from outcomes via dopamine feedback

Software analogue: Choose a worker, block competitors, run the routine, adjust policy from results.

Core Responsibilities

Gate

  • Accept and queue jobs
  • Choose which runs now vs later
  • Manage job priority and scheduling

Specify

  • Lock purpose, inputs, allowed tools/scopes
  • Set budgets and success criteria
  • Define safety constraints and policies

Supervise

  • Monitor checkpoints and heartbeats
  • Handle retries and escalation
  • Throttle to avoid starving the Prime

Conclude

  • Mark pass/fail status
  • Emit artifacts and diffs
  • Write append-only Job Ledger

Learn

  • Update routing/priority heuristics from outcomes
  • Adjust policies based on success/failure patterns
  • Optimize resource allocation

Inputs & Outputs

Inputs (from Prime/UI/schedule)

  • Job Specification: Purpose, inputs, capabilities, budgets
  • Persona-lite Rubric: Tone and values constraints
  • Success Criteria: Clear definition of completion
  • Safety Flags: Risk assessment and constraints

Outputs

  • Artifacts: Files, datasets, generated content
  • Diffs: External mutations and changes
  • Neocortex Intake Packets: Findings with confidence & provenance
  • Telemetry: Performance and usage metrics
  • Job Ledger Entry: Complete record of job execution

Boundaries

What BG Is

  • Action-selection & orchestration: Chooses and manages tasks
  • Worker supervisor: Monitors and controls sub-agents
  • Personality attenuator: Maintains "Prime-lite" tone/values only

What BG Isn't

  • Planner: No broad task decomposition UI
  • Knowledge integrator: That's Neocortex's role
  • Pruner: That's Glymphatic System's role
  • Chat multiplexer: That's Broca's role

Lifecycle

Job States

queued → starting → running → (paused) → completed | failed | canceled | expired

queued → starting → running → (paused) → completed | failed | canceled | expired

queued → starting → running → (paused) → completed | failed | canceled | expired

Start Phase

  • Acquire scoped capabilities
  • Hydrate minimal context (read-only dossiers/facts)
  • Launch worker with defined parameters

Run Phase

  • Worker emits checkpoints/heartbeats
  • BG enforces budgets and handles retries
  • Monitor for completion or failure conditions

Finish Phase

  • Collect artifacts and compute diffs
  • Require approval per policy
  • Write Job Ledger entry
  • Release scopes and cleanup

Safety & Policy

Default Policies

  • Persona-lite: No deep memory copy
  • Read-only access: Use dossiers/fact ledger as needed
  • Budget enforcement: Strict resource limits
  • Approval gates: Required for external changes

Safety Mechanisms

  • Scope isolation: Jobs run in isolated environments
  • Resource limits: CPU, memory, and time constraints
  • Approval workflows: Human oversight for critical operations
  • Audit trails: Complete logging of all actions

Configuration

Environment Variables

BG_MAX_CONCURRENT_JOBS=5
BG_DEFAULT_TIMEOUT=3600
BG_RETRY_ATTEMPTS=3
BG_APPROVAL_REQUIRED=true
BG_LOG_LEVEL=INFO

BG_MAX_CONCURRENT_JOBS=5 BG_DEFAULT_TIMEOUT=3600 BG_RETRY_ATTEMPTS=3 BG_APPROVAL_REQUIRED=true BG_LOG_LEVEL=INFO

queued → starting → running → (paused) → completed | failed | canceled | expired

Policy Configuration

  • Job Limits: Maximum concurrent jobs
  • Timeout Settings: Default and per-job timeouts
  • Retry Logic: Number of attempts and backoff strategy
  • Approval Requirements: When human approval is needed

Integration Points

With Prime/UI

  • Receives job specifications and requirements
  • Reports status and completion
  • Handles user interactions and approvals

With Sub-Agents

  • Launches and monitors worker processes
  • Provides context and capabilities
  • Collects results and artifacts

With Memory Systems

  • Accesses dossiers and fact ledgers
  • Stores job results and telemetry
  • Maintains job history and patterns

With Neocortex

  • Sends intake packets with findings
  • Provides confidence scores and provenance
  • Enables knowledge integration

Monitoring and Metrics

Key Metrics

  • Job Success Rate: Percentage of completed jobs
  • Average Completion Time: Time from start to finish
  • Resource Utilization: CPU, memory, and storage usage
  • Queue Length: Number of pending jobs

Health Monitoring

  • Worker Health: Status of active sub-agents
  • Resource Availability: Available capacity for new jobs
  • Error Rates: Frequency of failures and retries
  • Performance Trends: Historical performance data

Job Ledger

Record Structure

  • Job ID: Unique identifier
  • Specification: Original job requirements
  • Timeline: Start, checkpoint, and completion times
  • Results: Success/failure status and artifacts
  • Telemetry: Performance and resource usage
  • Approvals: Human oversight and decisions

Query Interface

  • Job History: Search and filter past jobs
  • Performance Analysis: Identify patterns and bottlenecks
  • Audit Trails: Complete record of all actions
  • Reporting: Generate summaries and insights

Advanced Features

Dynamic Scaling

  • Auto-scaling: Adjust resources based on demand
  • Load balancing: Distribute jobs across available workers
  • Priority queuing: Handle urgent jobs first

Learning and Adaptation

  • Success Pattern Recognition: Identify what works
  • Failure Analysis: Learn from mistakes
  • Resource Optimization: Improve efficiency over time
  • Policy Refinement: Adjust rules based on experience

Troubleshooting

Common Issues

  • Job Timeouts: Adjust timeout settings or optimize jobs
  • Resource Exhaustion: Increase limits or improve efficiency
  • Approval Bottlenecks: Streamline approval processes
  • Worker Failures: Check worker health and configuration

Debug Tools

  • Job Inspector: Detailed view of job execution
  • Resource Monitor: Real-time resource usage
  • Log Analyzer: Search and analyze job logs
  • Performance Profiler: Identify bottlenecks

Future Enhancements

Planned Features

  • Advanced Scheduling: More sophisticated job scheduling
  • Dynamic Policies: Adaptive policy adjustment
  • Enhanced Monitoring: Better observability and debugging
  • Integration Improvements: Better connectivity with other components

Research Areas

  • Optimization Algorithms: Better resource allocation
  • Failure Prediction: Proactive issue detection
  • Learning Systems: Improved adaptation and learning
  • Security Enhancements: Better isolation and protection

Related Components

Basal Ganglia - The task orchestrator of SanctumOS, ensuring efficient and controlled execution of complex workflows.