lunas-os

Imported from iamthetonyb/lunas-os (AGENTS.md). Install upstream with npx skills add iamthetonyb/lunas-os. Copyright stays with the author.

AGENTS.md — LUNAS-OS Autonomous Operations

Multi-agent orchestration for construction cleanup operations. Self-evolving system that learns from every intake, dispatch, and completion.

Architecture

                     ┌──────────────┐
                     │   LUNAS AI   │
                     │   (Master)   │
                     │   L4 Trust   │
                     └──────┬───────┘
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
          ▼                 ▼                 ▼
    ┌───────────┐    ┌───────────┐    ┌───────────┐
    │ SCHEDULER │    │ DISPATCH  │    │  INSIGHT   │
    │  Agent    │    │  Agent    │    │  Agent     │
    │ L3 (Act)  │    │ L3 (Act)  │    │ L2 (Learn) │
    └───────────┘    └───────────┘    └───────────┘
          │                 │                 │
          ▼                 ▼                 ▼
    ┌───────────┐    ┌───────────┐    ┌───────────┐
    │  Convex   │    │  Convex   │    │  RAG KB   │
    │  Queries  │    │ Mutations │    │  Vector   │
    └───────────┘    └───────────┘    └───────────┘
                            │
                     ┌──────┴───────┐
                     │  FOREMAN UI  │
                     │  (Chat/Voice)│
                     └──────────────┘

Agent Registry

Master (LUNAS AI Chat Widget)

Responsibilities:

• Answer questions about schedule, jobs, crews, billing
• Execute assignments, reschedules, dispatches on command
• Route complex multi-step operations to sub-agents
• Maintain conversation context across interactions
• Log all decisions to audit trail

Scheduler Agent

Responsibilities:

• Analyze incoming jobs vs crew capacity (capacityPerDay)
• Suggest optimal foreman-crew pairings based on:
  • Service type ↔ crew skills
  • Geographic clustering (community proximity)
  • Workload balance across foremen
  • Historical assignment success rates
• Auto-assign if confidence > 0.85, else flag for human review

Decision Schema:

action: "auto_assign_foreman"
input:
  jobId: "jrs_abc123"
  service: "Clean Final"
  community: "Caprock"
  lot: "42"
confidence: 0.92
output:
  foremanName: "Anahi"
  crewName: "Carmen"
  reason: "Anahi handles 78% of Caprock jobs, Carmen's crew has capacity"

Dispatch Agent

Responsibilities:

• Group assigned jobs into dispatch batches by crew
• Verify all jobs have foreman + crew before dispatch
• Create dispatch batch records in Convex
• Generate run sheets (PDF) for each crew
• Flag anomalies (double-booked lots, missing walk times)

Insight Agent

Responsibilities:

• Analyze completed jobs for patterns
• Track per-community service frequency
• Identify builder ordering patterns (seasonality, lot sequences)
• Detect pricing anomalies in blue book entries
• Ingest learned patterns into RAG knowledge base
• Generate weekly operational summaries

Learning Loop:

Completed Jobs → Pattern Analysis → Insight Extraction
    → RAG Ingest → Future Query Enhancement
    → Better Suggestions → Better Outcomes
    → More Completed Jobs (cycle continues)

Trust Tiers

Guardrails (apply at all trust tiers)

• Never delete job requests or dispatch batches without human confirmation
• Never modify billing/payment data autonomously
• Always log every write operation to aiDecisionLog
• Always show confidence score for autonomous decisions
• Escalate to human when confidence < 0.70
• Rate limit: Max 50 autonomous mutations per hour

Self-Evolution Protocol

Pattern Recognition → Skill Creation

When the AI identifies a repeating pattern (3+ occurrences):

1. Detect: Same community + service type → same foreman assigned
2. Extract: "Anahi handles 78% of Caprock Clean Final jobs"
3. Store: Ingest as RAG knowledge: "For Caprock Clean Final jobs, default to Anahi"
4. Apply: Next time a Caprock Clean Final intake arrives, auto-suggest Anahi
5. Validate: Track if the suggestion was accepted or overridden
6. Refine: If overridden >30% of the time, lower confidence and re-learn

Knowledge Distillation

The RAG knowledge base acts as the system's "compressed model":

Cloud Model (GPT-5.4 Nano)
    │
    ├─ Reasons over live data (queries)
    ├─ Makes decisions (mutations)
    ├─ Generates insights (patterns)
    │
    ▼
RAG Knowledge Base (Convex Vector Store)
    │
    ├─ Stores operational patterns
    ├─ Stores community-foreman affinities
    ├─ Stores builder ordering patterns
    ├─ Stores pricing benchmarks
    │
    ▼
Future Queries (enhanced with retrieved context)
    │
    └─ Better answers with fewer tokens
       (RAG provides context that the model
        would otherwise need to reason about)

This is soft distillation — the cloud model's reasoning gets persisted as structured knowledge, making future queries cheaper and faster.

Insight Ingestion Pipeline

// Scheduled: runs weekly
async function weeklyInsightPipeline() {
    // 1. Query completed jobs from past week
    const jobs = await getCompletedJobs({ lastDays: 7 });

    // 2. Analyze patterns with GPT-5.4 Nano
    const insights = await analyzePatterns(jobs);

    // 3. Ingest into RAG knowledge base
    for (const insight of insights) {
        await rag.add({
            namespace: "operations",
            text: insight.text,
        });
    }

    // 4. Log the learning event
    await logDecision({
        action: "weekly_insight_ingest",
        input: JSON.stringify({ jobCount: jobs.length }),
        output: JSON.stringify({ insightCount: insights.length }),
        confidence: 1.0,
        source: "scheduled",
    });
}

Decision Audit Trail

Every autonomous action is logged to aiDecisionLog table:

Confidence Thresholds

Scheduled Agents (Future — Convex Cron Jobs)

Model Strategy

Model Distillation Pipeline (nanochat + 0wav inspired)

Goal: Train a small local model (LUNAS-Nano) from operational data, deploy to CPU for $0 inference on routine queries.

Pipeline:

Decision Logs (Convex) → Export JSONL → 3-Stage Curriculum SFT → GGUF Quantize → Ollama Deploy

Step 1: Data Collection (convex/distillation.ts)

• High-confidence decisions (>0.85) become "gold" training examples (weight 2.0x)
• Conversation threads with successful tool use become SFT pairs
• Export: pnpm tsx scripts/export-training-data.ts

Step 2: Training (nanochat pipeline on H100/A100)

• 3-stage curriculum (0wav pattern):
  • Foundation: uniform weights, learn general patterns (20 epochs)
  • Enrichment: cosine ramp quality weights (30 epochs)
  • Precision: gold boost 1.5x, full quality (50 epochs)
• Architecture: nanochat depth-12 (GPT-1 class, ~5 min on H100)
• Config: training/config.yaml

Step 3: Quantization

• Convert to GGUF q4_0 (4-bit, smallest, fast on CPU)
• ~50MB model file for CPU inference

Step 4: Deployment (training/Modelfile)

ollama create lunas-nano -f training/Modelfile
ollama run lunas-nano "What's on the schedule?"

Step 5: Routing

• Local model handles: schedule lookups, entity queries, status checks
• Cloud model handles: write operations, multi-step reasoning, RAG search, low-confidence queries
• ATLAS-style routing scorer decides which model to use per query

Evaluation & Red-Teaming (promptfoo)

Eval Harness (evals/promptfooconfig.yaml)

• 25+ test cases covering all 17 tools
• Schedule queries, foreman assignment, RAG search, dispatch, bilingual, edge cases
• Assertion types: tool selection, content quality, LLM rubric, latency, cost
• Run: npx promptfoo eval -c evals/promptfooconfig.yaml

Red Team (evals/promptfoo-redteam.yaml)

• RBAC attacks (role-based access control bypass)
• Prompt injection (via job notes, community names)
• Data exfiltration (builder pricing cross-leak)
• Hallucination detection (invented job IDs)
• OWASP LLM Top 10 coverage
• Bilingual attack vectors (EN/ES)
• Run: npx promptfoo redteam run -c evals/promptfoo-redteam.yaml

Continuous Monitoring

• Weekly eval runs via cron
• PR-gated evals: any change to lib/ai/* triggers eval
• 95% pass rate quality gate
• Compare local vs cloud model performance

Integration Points

Security

• All tool calls go through the Next.js API route (server-side only)
• Convex mutations require valid function references (type-safe)
• No raw database access from the client
• OpenRouter/OpenAI keys stored in env vars, never client-exposed
• Decision audit log is append-only (no delete mutations exposed)
• Rate limiting on chat API route prevents token abuse
• Red-team eval runs weekly to detect new vulnerabilities
• RBAC enforcement: write tools require ADMIN role context