@spekra.in/agent-os 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/Booker/README.md +41 -0
  2. package/Booker/package.json +11 -0
  3. package/Booker/src/agent.js +15 -0
  4. package/Booker/src/calendar-adapter.js +75 -0
  5. package/Booker/src/index.js +4 -0
  6. package/Booker/src/intake-parser.js +96 -0
  7. package/Booker/src/validation.js +34 -0
  8. package/Booker/test/booker.test.js +35 -0
  9. package/CashHound/README.md +181 -0
  10. package/CashHound/package.json +21 -0
  11. package/CashHound/src/agent.js +621 -0
  12. package/CashHound/src/bank-reconciler.js +66 -0
  13. package/CashHound/src/dunning.js +380 -0
  14. package/CashHound/src/index.js +32 -0
  15. package/CashHound/src/invoice.js +371 -0
  16. package/CashHound/src/mobile.js +35 -0
  17. package/CashHound/src/npv-optimizer.js +259 -0
  18. package/CashHound/test/advanced.test.js +44 -0
  19. package/CashHound/test/cashhound.test.js +530 -0
  20. package/CashHound/test/mobile.test.js +25 -0
  21. package/CashHound/test/security.test.js +35 -0
  22. package/Clerk/README.md +30 -0
  23. package/Clerk/package.json +11 -0
  24. package/Clerk/src/agent.js +18 -0
  25. package/Clerk/src/index.js +2 -0
  26. package/Clerk/src/reconciliation.js +52 -0
  27. package/Clerk/test/clerk.test.js +39 -0
  28. package/LocalRoar/README.md +37 -0
  29. package/LocalRoar/package.json +13 -0
  30. package/LocalRoar/src/agent.js +70 -0
  31. package/LocalRoar/src/booking-router.js +74 -0
  32. package/LocalRoar/src/feedback-interceptor.js +47 -0
  33. package/LocalRoar/src/index.js +7 -0
  34. package/LocalRoar/src/lead-engine.js +52 -0
  35. package/LocalRoar/src/mobile.js +23 -0
  36. package/LocalRoar/src/review-booster.js +24 -0
  37. package/LocalRoar/src/route-density.js +46 -0
  38. package/LocalRoar/test/advanced.test.js +41 -0
  39. package/LocalRoar/test/localroar.test.js +59 -0
  40. package/LocalRoar/test/mobile.test.js +12 -0
  41. package/OmniLife/README.md +39 -0
  42. package/OmniLife/package.json +13 -0
  43. package/OmniLife/src/agent.js +47 -0
  44. package/OmniLife/src/bill-negotiator.js +43 -0
  45. package/OmniLife/src/browser-cancel.js +28 -0
  46. package/OmniLife/src/conflict-engine.js +49 -0
  47. package/OmniLife/src/index.js +6 -0
  48. package/OmniLife/src/mobile.js +18 -0
  49. package/OmniLife/src/subscription-manager.js +66 -0
  50. package/OmniLife/test/advanced.test.js +29 -0
  51. package/OmniLife/test/mobile.test.js +12 -0
  52. package/OmniLife/test/omnilife.test.js +71 -0
  53. package/PulseMD/README.md +42 -0
  54. package/PulseMD/package.json +13 -0
  55. package/PulseMD/src/agent.js +67 -0
  56. package/PulseMD/src/ambient-scribe.js +46 -0
  57. package/PulseMD/src/auth.js +63 -0
  58. package/PulseMD/src/charting.js +54 -0
  59. package/PulseMD/src/index.js +7 -0
  60. package/PulseMD/src/mobile.js +18 -0
  61. package/PulseMD/src/prior-auth.js +39 -0
  62. package/PulseMD/src/safety-guard.js +88 -0
  63. package/PulseMD/test/advanced.test.js +50 -0
  64. package/PulseMD/test/mobile.test.js +12 -0
  65. package/PulseMD/test/pulsemd.test.js +71 -0
  66. package/README.md +208 -2
  67. package/ResolveX/README.md +274 -0
  68. package/ResolveX/package.json +20 -0
  69. package/ResolveX/src/agent.js +679 -0
  70. package/ResolveX/src/carrier-listener.js +405 -0
  71. package/ResolveX/src/diagnosis.js +315 -0
  72. package/ResolveX/src/index.js +36 -0
  73. package/ResolveX/src/mobile.js +31 -0
  74. package/ResolveX/src/policy.js +325 -0
  75. package/ResolveX/src/vision.js +384 -0
  76. package/ResolveX/test/advanced.test.js +445 -0
  77. package/ResolveX/test/mobile.test.js +15 -0
  78. package/ResolveX/test/resolvex.test.js +428 -0
  79. package/SentinelMesh/README.md +51 -0
  80. package/SentinelMesh/package.json +13 -0
  81. package/SentinelMesh/src/governor.js +61 -0
  82. package/SentinelMesh/src/index.js +4 -0
  83. package/SentinelMesh/src/mobile.js +19 -0
  84. package/SentinelMesh/src/policy.js +63 -0
  85. package/SentinelMesh/src/sandbox.js +152 -0
  86. package/SentinelMesh/test/mobile.test.js +12 -0
  87. package/SentinelMesh/test/sentinel.test.js +135 -0
  88. package/Sidekick/README.md +43 -0
  89. package/Sidekick/package.json +11 -0
  90. package/Sidekick/src/agent.js +15 -0
  91. package/Sidekick/src/evidence.js +45 -0
  92. package/Sidekick/src/index.js +3 -0
  93. package/Sidekick/src/validation.js +15 -0
  94. package/Sidekick/test/sidekick.test.js +33 -0
  95. package/agent-os-mobile/README.md +26 -0
  96. package/agent-os-mobile/src/api.js +97 -0
  97. package/agent-os-mobile/src/biometric.js +41 -0
  98. package/agent-os-mobile/src/components/ApprovalStack.js +207 -0
  99. package/agent-os-mobile/src/components/OutcomeCard.js +98 -0
  100. package/agent-os-mobile/src/memory-graph.js +114 -0
  101. package/agent-os-mobile/src/screens/CashHoundMobileScreen.js +111 -0
  102. package/agent-os-mobile/src/screens/LocalRoarMobileScreen.js +183 -0
  103. package/agent-os-mobile/src/screens/OmniLifeMobileScreen.js +111 -0
  104. package/agent-os-mobile/src/screens/PulseMDMobileScreen.js +55 -0
  105. package/agent-os-mobile/src/screens/ResolveXMobileScreen.js +96 -0
  106. package/agent-os-mobile/src/screens/SentinelMeshMobileScreen.js +199 -0
  107. package/agent-os-mobile/src/self-healer.js +104 -0
  108. package/agent-os-mobile/src/speculative-verifier.js +69 -0
  109. package/agent-os-mobile/src/spekra-bridge.js +216 -0
  110. package/agent-os-mobile/src/swarm.js +72 -0
  111. package/agent-os-mobile/src/voice.js +51 -0
  112. package/bin/agentos.js +338 -0
  113. package/package.json +52 -4
  114. package/src/index.js +95 -0
  115. package/src/llm-gateway.js +226 -0
@@ -0,0 +1,7 @@
1
+ export { ChartingEngine } from './charting.js';
2
+ export { PAYER_GUIDELINES, PriorAuthEngine } from './prior-auth.js';
3
+ export { ClinicianAuth } from './auth.js';
4
+ export { PulseMDAgent } from './agent.js';
5
+ export { PulseMDMobileAdapter } from './mobile.js';
6
+ export { ClinicalSafetyGuard, CONTRAINDICATION_RULES } from './safety-guard.js';
7
+ export { AmbientMedicalScribe } from './ambient-scribe.js';
@@ -0,0 +1,18 @@
1
+ /**
2
+ * PulseMD Mobile Adapter: Formats mobile clinical cards and 1-tap SOAP signing payloads.
3
+ */
4
+
5
+ export class PulseMDMobileAdapter {
6
+ constructor(agent) {
7
+ this.agent = agent;
8
+ }
9
+
10
+ getMobileOutcomeCard() {
11
+ return {
12
+ title: 'PulseMD Clinical Operations',
13
+ outcomeMetric: '100% Verified',
14
+ signedEncounters: this.agent.signedRecords.length,
15
+ statusBadge: 'CLINICIAN_OVERSIGHT_ACTIVE'
16
+ };
17
+ }
18
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * PulseMD Prior Authorization Builder: Compiles criteria checklist and clinical justifications.
3
+ */
4
+
5
+ export const PAYER_GUIDELINES = {
6
+ 'mri_lumbar': {
7
+ name: 'Lumbar Spine MRI',
8
+ prerequisites: ['physical_therapy_completed', 'conservative_management_6_weeks', 'radiograph_completed'],
9
+ cptCode: '72148'
10
+ },
11
+ 'glp1_semaglutide': {
12
+ name: 'GLP-1 Receptor Agonist',
13
+ prerequisites: ['documented_hba1c_elevated', 'metformin_trial_failed'],
14
+ cptCode: 'J3490'
15
+ }
16
+ };
17
+
18
+ export class PriorAuthEngine {
19
+ buildAuthPacket(patientId, procedureKey, patientHistory = {}) {
20
+ const guideline = PAYER_GUIDELINES[procedureKey];
21
+ if (!guideline) {
22
+ throw new Error(`Procedure ${procedureKey} is not registered in guidelines.`);
23
+ }
24
+
25
+ const missingPrerequisites = guideline.prerequisites.filter(req => !patientHistory[req]);
26
+ const isCompliant = missingPrerequisites.length === 0;
27
+
28
+ return {
29
+ authPacketId: `pa_${Date.now()}`,
30
+ patientId,
31
+ procedureName: guideline.name,
32
+ cptCode: guideline.cptCode,
33
+ isCompliant,
34
+ missingPrerequisites,
35
+ status: isCompliant ? 'READY_FOR_CLINICIAN_REVIEW' : 'DEFICIENT_CRITERIA',
36
+ timestamp: new Date().toISOString()
37
+ };
38
+ }
39
+ }
@@ -0,0 +1,88 @@
1
+ /**
2
+ * PulseMD Clinical Safety Guard: Evaluates drug-drug interactions, patient allergy alerts,
3
+ * and contraindications against evidence-based pharmacological rules.
4
+ */
5
+
6
+ export const CONTRAINDICATION_RULES = [
7
+ {
8
+ drugClass: 'nsaid',
9
+ names: ['ibuprofen', 'naproxen', 'ketorolac', 'meloxicam'],
10
+ conflictConditions: ['peptic_ulcer', 'chronic_kidney_disease', 'severe_renal_impairment'],
11
+ severity: 'HIGH_RISK',
12
+ warning: 'NSAIDs are contraindicated in patients with active peptic ulcer disease or severe renal impairment (risk of GI bleed / acute kidney injury).'
13
+ },
14
+ {
15
+ drugClass: 'ace_inhibitor',
16
+ names: ['lisinopril', 'enalapril', 'ramipril'],
17
+ conflictDrugs: ['spironolactone', 'potassium_chloride'],
18
+ severity: 'CRITICAL',
19
+ warning: 'Concurrent ACE inhibitor and potassium-sparing agent carries high risk of life-threatening hyperkalemia.'
20
+ }
21
+ ];
22
+
23
+ export class ClinicalSafetyGuard {
24
+ evaluateSafety(proposedMedications = [], patientProfile = {}) {
25
+ const { allergies = [], existingConditions = [], currentMedications = [] } = patientProfile;
26
+ const alerts = [];
27
+
28
+ const lowerProposed = proposedMedications.map(m => m.toLowerCase());
29
+ const lowerAllergies = allergies.map(a => a.toLowerCase());
30
+ const lowerConditions = existingConditions.map(c => c.toLowerCase());
31
+ const lowerCurrentMeds = currentMedications.map(m => m.toLowerCase());
32
+
33
+ // 1. Allergy check
34
+ for (const med of lowerProposed) {
35
+ for (const allergy of lowerAllergies) {
36
+ if (med.includes(allergy) || allergy.includes(med)) {
37
+ alerts.push({
38
+ type: 'ALLERGY_ALERT',
39
+ severity: 'CRITICAL',
40
+ medication: med,
41
+ allergy,
42
+ message: `FATAL ALLERGY WARNING: Proposed medication '${med}' matches patient documented allergy to '${allergy}'.`
43
+ });
44
+ }
45
+ }
46
+ }
47
+
48
+ // 2. Condition & Drug Contraindications
49
+ for (const rule of CONTRAINDICATION_RULES) {
50
+ const matchesProposed = rule.names.some(name => lowerProposed.some(p => p.includes(name)));
51
+ if (matchesProposed) {
52
+ // Condition conflict
53
+ if (rule.conflictConditions) {
54
+ const conditionMatch = rule.conflictConditions.find(cond => lowerConditions.includes(cond));
55
+ if (conditionMatch) {
56
+ alerts.push({
57
+ type: 'CONDITION_CONTRAINDICATION',
58
+ severity: rule.severity,
59
+ rule: rule.drugClass,
60
+ condition: conditionMatch,
61
+ message: rule.warning
62
+ });
63
+ }
64
+ }
65
+
66
+ // Current drug conflict
67
+ if (rule.conflictDrugs) {
68
+ const drugMatch = rule.conflictDrugs.find(cd => lowerCurrentMeds.some(m => m.includes(cd)));
69
+ if (drugMatch) {
70
+ alerts.push({
71
+ type: 'DRUG_DRUG_INTERACTION',
72
+ severity: rule.severity,
73
+ rule: rule.drugClass,
74
+ conflictingDrug: drugMatch,
75
+ message: rule.warning
76
+ });
77
+ }
78
+ }
79
+ }
80
+ }
81
+
82
+ return {
83
+ safeToPrescribe: alerts.length === 0,
84
+ alertsCount: alerts.length,
85
+ alerts
86
+ };
87
+ }
88
+ }
@@ -0,0 +1,50 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { ClinicalSafetyGuard, AmbientMedicalScribe } from '../src/index.js';
4
+
5
+ test('PulseMD Safety Guard: detects fatal allergy conflicts and drug contraindications', () => {
6
+ const guard = new ClinicalSafetyGuard();
7
+
8
+ // Test 1: Allergy alert
9
+ const allergyProfile = {
10
+ allergies: ['penicillin'],
11
+ currentMedications: []
12
+ };
13
+ const allergyCheck = guard.evaluateSafety(['Amoxicillin-Penicillin VK'], allergyProfile);
14
+ assert.equal(allergyCheck.safeToPrescribe, false);
15
+ assert.equal(allergyCheck.alerts[0].type, 'ALLERGY_ALERT');
16
+
17
+ // Test 2: NSAID with active peptic ulcer disease
18
+ const ulcerProfile = {
19
+ allergies: [],
20
+ existingConditions: ['peptic_ulcer'],
21
+ currentMedications: []
22
+ };
23
+ const nsaidCheck = guard.evaluateSafety(['ibuprofen 800mg'], ulcerProfile);
24
+ assert.equal(nsaidCheck.safeToPrescribe, false);
25
+ assert.equal(nsaidCheck.alerts[0].type, 'CONDITION_CONTRAINDICATION');
26
+
27
+ // Test 3: Safe prescription
28
+ const safeProfile = {
29
+ allergies: [],
30
+ existingConditions: [],
31
+ currentMedications: []
32
+ };
33
+ const safeCheck = guard.evaluateSafety(['acetaminophen 500mg'], safeProfile);
34
+ assert.equal(safeCheck.safeToPrescribe, true);
35
+ assert.equal(safeCheck.alertsCount, 0);
36
+ });
37
+
38
+ test('PulseMD Ambient Scribe: extracts structured observations from doctor-patient audio stream', () => {
39
+ const scribe = new AmbientMedicalScribe();
40
+ const dialogue = [
41
+ { speaker: 'DOCTOR', text: 'Good morning, what brings you into the clinic today?' },
42
+ { speaker: 'PATIENT', text: 'Doctor, I have been having severe chest pain and pressure for the past 3 days.' },
43
+ { speaker: 'DOCTOR', text: 'Understood, let us order an immediate ECG and cardiac enzymes.' }
44
+ ];
45
+
46
+ const result = scribe.processDialogueStream(dialogue);
47
+ assert.ok(result.extractedObservations.symptoms.includes('Chest Pressure/Pain'));
48
+ assert.equal(result.extractedObservations.clinicalDuration, 'Acute (3-4 days)');
49
+ assert.equal(result.fhirResourceDraft.resourceType, 'ClinicalImpression');
50
+ });
@@ -0,0 +1,12 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { PulseMDAgent, PulseMDMobileAdapter } from '../src/index.js';
4
+
5
+ test('PulseMD Mobile Adapter: formats mobile clinical outcome cards', () => {
6
+ const agent = new PulseMDAgent();
7
+ const mobile = new PulseMDMobileAdapter(agent);
8
+
9
+ const card = mobile.getMobileOutcomeCard();
10
+ assert.equal(card.title, 'PulseMD Clinical Operations');
11
+ assert.equal(card.statusBadge, 'CLINICIAN_OVERSIGHT_ACTIVE');
12
+ });
@@ -0,0 +1,71 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { PulseMDAgent, ClinicianAuth } from '../src/index.js';
4
+
5
+ test('PulseMD: drafts clinical SOAP note, redacts PHI, and gates on verified clinician signature', () => {
6
+ const agent = new PulseMDAgent();
7
+ const encounter = {
8
+ patientId: 'pt-1001',
9
+ chiefComplaint: 'Right knee pain after sports injury. Patient SSN 123-45-6789, Phone 555-123-4567',
10
+ vitals: { bp: '124/82', hr: '76', temp: '98.4F' },
11
+ conversation: 'Patient reports twist while playing soccer 3 days ago. Contact: john@example.com.',
12
+ clinicianName: 'Dr. Sarah Smith, MD'
13
+ };
14
+
15
+ const draftResult = agent.processEncounter(encounter);
16
+ assert.equal(draftResult.status, 'AWAITING_CLINICIAN_SIGNATURE');
17
+
18
+ // Verify PHI / PII was redacted
19
+ assert.ok(draftResult.draftNote.soap.subjective.includes('[REDACTED_SSN]'));
20
+ assert.ok(draftResult.draftNote.soap.subjective.includes('[REDACTED_PHONE]'));
21
+ assert.ok(draftResult.draftNote.soap.subjective.includes('[REDACTED_EMAIL]'));
22
+
23
+ // Attempting to finalize note with no or invalid token should throw
24
+ assert.throws(() => {
25
+ agent.signAndFinalizeNote(draftResult.draftNote.draftId, 'dr-smith-md', {}, 'invalid-token');
26
+ }, /Unauthorized signature attempt/);
27
+
28
+ // Generate valid cryptographic signature token
29
+ const validToken = ClinicianAuth.generateToken('dr-smith-md', 'PHYSICIAN');
30
+ const finalized = agent.signAndFinalizeNote(draftResult.draftNote.draftId, 'dr-smith-md', {}, validToken);
31
+ assert.equal(finalized.status, 'FINALIZED_AND_LOCKED');
32
+ assert.equal(finalized.clinicianId, 'dr-smith-md');
33
+ assert.equal(finalized.verifiedRole, 'PHYSICIAN');
34
+ });
35
+
36
+ test('PulseMD Security: rejects forged or mismatched clinician signature tokens', () => {
37
+ const agent = new PulseMDAgent();
38
+ const draft = agent.processEncounter({
39
+ patientId: 'pt-2002',
40
+ chiefComplaint: 'Hypertension check'
41
+ });
42
+
43
+ // Token created for another doctor
44
+ const tokenForOtherDoc = ClinicianAuth.generateToken('dr-other-doc', 'PHYSICIAN');
45
+ assert.throws(() => {
46
+ agent.signAndFinalizeNote(draft.draftNote.draftId, 'dr-target-doc', {}, tokenForOtherDoc);
47
+ }, /does not match claimed/);
48
+ });
49
+
50
+ test('PulseMD: flags missing prior-authorization prerequisites for imaging', () => {
51
+ const agent = new PulseMDAgent();
52
+
53
+ const incompleteHistory = {
54
+ radiograph_completed: true
55
+ };
56
+
57
+ const deficient = agent.evaluatePriorAuth('pt-1001', 'mri_lumbar', incompleteHistory);
58
+ assert.equal(deficient.action, 'FLAG_DEFICIENCY');
59
+ assert.ok(deficient.missing.includes('physical_therapy_completed'));
60
+
61
+ const completeHistory = {
62
+ physical_therapy_completed: true,
63
+ conservative_management_6_weeks: true,
64
+ radiograph_completed: true
65
+ };
66
+
67
+ const ready = agent.evaluatePriorAuth('pt-1001', 'mri_lumbar', completeHistory);
68
+ assert.equal(ready.action, 'SUBMIT_FOR_CLINICIAN_APPROVAL');
69
+ assert.equal(ready.packet.isCompliant, true);
70
+ assert.equal(ready.packet.cptCode, '72148');
71
+ });
package/README.md CHANGED
@@ -1,3 +1,209 @@
1
- # Temporary Holding Version
1
+ # ⚡ AgentOS — The Autonomous Agent Operating System
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![Spekra Product](https://img.shields.io/badge/Product%20of-Spekra.in-38BDF8.svg)](https://spekra.in)
4
+ [![npm version](https://img.shields.io/badge/npm-%40spekra.in%2Fagent--os-CB3837.svg)](https://www.npmjs.com/package/@spekra.in/agent-os)
5
+ [![CI Status](https://github.com/subash-thiruppathi/agent-os/actions/workflows/ci.yml/badge.svg)](https://github.com/subash-thiruppathi/agent-os/actions)
6
+ [![Tests Passing](https://img.shields.io/badge/Tests-124%2F124%20Passing-10B981.svg)](https://github.com/subash-thiruppathi/agent-os)
7
+ [![Node Version](https://img.shields.io/badge/Node-%3E%3D20.0.0-3B82F6.svg)](https://nodejs.org/)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
+ [![Zero-Trust](https://img.shields.io/badge/Security-Zero--Trust%20Sandboxed-8B5CF6.svg)](https://github.com/subash-thiruppathi/agent-os)
10
+
11
+ **AgentOS** is an outcome-driven, production-grade operating system for autonomous AI agents, engineered under the **[Spekra](https://spekra.in)** autonomous intelligence and operational reliability ecosystem. It combines a zero-trust governance fabric, speculative action verifiers, cross-agent memory graphs, auto-healing execution rails, and a native mobile command cockpit for real-time human oversight.
12
+
13
+ ---
14
+
15
+ ## 🏛️ System Architecture
16
+
17
+ ```mermaid
18
+ flowchart TD
19
+ User([👤 Operator / Mobile User]) <--> Cockpit[📱 AgentOS Mobile Cockpit<br/>FaceID · Voice · Biometrics]
20
+ Cockpit <--> Gateway[🛡️ Server Approval Gateway<br/>HMAC Nonce · Replay Guard]
21
+
22
+ subgraph CoreOS ["⚡ AgentOS Runtime Fabric"]
23
+ Gateway --> Verifier[🔍 Speculative Verifier<br/>Math Audit · FDCPA Tone Gate]
24
+ Verifier --> MemoryGraph[(🧠 AgentMemoryGraph<br/>Privacy Partitions: PHI / Conf / Org)]
25
+ Verifier --> SelfHealer[🩹 AgentSelfHealer<br/>Auto-Retry · Failover Rails]
26
+ SelfHealer --> Swarm[🐝 AgentOS Swarm Orchestrator]
27
+ end
28
+
29
+ subgraph Agents ["🤖 Autonomous Agent Fleet"]
30
+ Swarm --> CashHound[🪙 CashHound<br/>Fintech Debt Recovery]
31
+ Swarm --> ResolveX[⚡ ResolveX<br/>Dispute Concierge]
32
+ Swarm --> SentinelMesh[🛡️ SentinelMesh<br/>Zero-Trust Governor]
33
+ Swarm --> LocalRoar[📣 LocalRoar<br/>Growth & Route Density]
34
+ Swarm --> PulseMD[🩺 PulseMD<br/>Clinical Scribe & Prior-Auth]
35
+ Swarm --> OmniLife[🌐 OmniLife<br/>Sovereign Life OS]
36
+ Swarm --> Booker[📅 Booker<br/>Intake & Scheduling]
37
+ end
38
+
39
+ SentinelMesh --> Ledger[(📜 Tamper-Evident Ledger<br/>SHA-256 Frozen Blocks)]
40
+ ```
41
+
42
+ ---
43
+
44
+ ## 🚀 The 6 Core Platform Engines
45
+
46
+ ### 1. 🧠 Cross-Agent Memory Graph (`AgentMemoryGraph`)
47
+ - Cross-agent semantic facts with **cryptographic privacy tiers**: `PUBLIC`, `ORGANIZATION`, `CONFIDENTIAL`, and `RESTRICTED_PHI`.
48
+ - Hard boundaries prevent medical facts from leaking into commercial dunning bots.
49
+ - Automatically supersedes outdated records with higher-confidence observations.
50
+
51
+ ### 2. 🩹 Self-Healing & Auto-Recovery (`AgentSelfHealer`)
52
+ - Automated fault classification: `429 Rate Limit`, `TRANSIENT_NETWORK`, `RAIL_UNAVAILABLE`, `AUTH_EXPIRED`.
53
+ - Intelligent exponential jittered backoff without dropping active agent tasks.
54
+ - Hot failover switching from primary rails (e.g. Stripe) to secondary rails (e.g. Adyen).
55
+
56
+ ### 3. 🔍 Speculative Verifier ("Second Pair of Eyes") (`SpeculativeVerifier`)
57
+ - Audits proposed actions **before** human operator presentation.
58
+ - Verifies exact minor-unit (cents) integer math reconciliations across line items.
59
+ - Scans outbound messages for prohibited coercion words (FDCPA debt collection compliance).
60
+
61
+ ### 4. 🐝 Cross-Agent Swarm Orchestrator (`AgentOSSwarm`)
62
+ - Pipelines complex multi-stage tasks across specialized agents:
63
+ `LocalRoar (Lead)` $\rightarrow$ `Booker (Intake)` $\rightarrow$ `Sidekick (Quote)` $\rightarrow$ `Clerk (Invoice)` $\rightarrow$ `SentinelMesh (Security Gate)`.
64
+
65
+ ### 5. 🔐 Biometric Hardware Authorization (`BiometricController`)
66
+ - Hardware-backed challenge-nonce generation prevents man-in-the-middle replays.
67
+ - Gates high-value transactions (> $1,000) behind FaceID / TouchID biometric signatures.
68
+
69
+ ### 6. 🎙️ Voice Cockpit Engine (`VoiceCockpit`)
70
+ - Hands-free natural language command interpretation.
71
+ - Parses intents, verifies authority levels, executes agent tasks, and streams synthesized audio responses.
72
+
73
+ ### 7. 🧠 Gemini AI Gateway & Speculative Guardrail (`AgentOSLLMGateway`)
74
+ - Integrates Google Gemini generative intelligence (`gemini-2.5-flash`) with mandatory pre-flight `SpeculativeVerifier` audits.
75
+ - Generates empathy-driven FDCPA-compliant dunning settlement notices, multi-speaker FHIR clinical SOAP notes, and high-value dispute resolution battlecards.
76
+ - Operates in live Gemini mode with `GEMINI_API_KEY` or falls back seamlessly to deterministic rule-based engines.
77
+
78
+ ---
79
+
80
+ ## 🤖 The Autonomous Agent Fleet
81
+
82
+ | Agent | Domain | Highlights |
83
+ | :--- | :--- | :--- |
84
+ | **🪙 CashHound** | B2B Working Capital & Recovery | Discounted Cash Flow NPV optimizer, ACH memo reconciler, respectful dunning tiers. |
85
+ | **⚡ ResolveX** | E-Commerce Dispute Concierge | Computer vision damage assessor (94.2% auto-resolution), carrier delay listener, SHA-256 idempotency refund replay guard. |
86
+ | **🛡️ SentinelMesh** | Zero-Trust Governance | Least-privilege sandboxing, immutable SHA-256 ledger blocks, dual-control high-value gates, emergency quarantine killswitch. |
87
+ | **📣 LocalRoar** | 24/7 Local Business Growth | SMS/WhatsApp intake, route-density proximity match (10–15% neighborhood discounts), 1–3 star private review interceptor. |
88
+ | **🩺 PulseMD** | Clinical Charting & Prior-Auth | Ambient dialogue extractor into FHIR SOAP notes, automatic PHI redaction (SSN, phone, email), drug-allergy contraindication guard. |
89
+ | **🌐 OmniLife** | Sovereign Life OS | Telecom bill negotiator battlecards, retention maze cancellation graph, passport 6-month international travel checker. |
90
+ | **📅 Booker** | Autonomous Scheduling | Unstructured intake parsing, double-booking prevention, calendar sync. |
91
+
92
+ ---
93
+
94
+ ## 📦 Installation & Quickstart
95
+
96
+ ### Option A: Install via npm (SDK & CLI)
97
+ ```bash
98
+ npm install @spekra.in/agent-os
99
+ ```
100
+
101
+ Import AgentOS primitives in your JavaScript / TypeScript application:
102
+ ```javascript
103
+ import {
104
+ SpeculativeVerifier,
105
+ AgentMemoryGraph,
106
+ MemoryPrivacyTier,
107
+ AgentSelfHealer,
108
+ SentinelGovernor,
109
+ SpekraTelemetryBridge,
110
+ AgentOSSwarm
111
+ } from '@spekra.in/agent-os';
112
+
113
+ // Run speculative math & tone verifier
114
+ const verifier = new SpeculativeVerifier();
115
+ const audit = verifier.verifyAction({
116
+ id: 'act-101',
117
+ amountCents: 45000,
118
+ breakdown: [{ amountCents: 45000 }],
119
+ title: 'Service Payment',
120
+ description: 'Standard invoice reminder'
121
+ });
122
+
123
+ console.log('Verified:', audit.verified);
124
+ ```
125
+
126
+ Run CLI diagnostics directly:
127
+ ```bash
128
+ npx agentos doctor
129
+ npx agentos fleet status
130
+ npx agentos swarm run
131
+ npx agentos audit --ledger
132
+ ```
133
+
134
+ ---
135
+
136
+ ### Option B: Monorepo Setup (Full Simulator & Mobile App)
137
+
138
+ #### 1. Clone & Install
139
+ ```bash
140
+ git clone https://github.com/subash-thiruppathi/agent-os.git
141
+ cd agent-os
142
+ ```
143
+
144
+ #### 2. Start the Unified Fleet Server & Dashboard
145
+ ```bash
146
+ npm start
147
+ ```
148
+ Open **`http://localhost:3000`** in your browser to access the live fleet control room.
149
+
150
+ #### 3. Launch Mobile Cockpit
151
+ ```bash
152
+ npm run mobile
153
+ ```
154
+ Press `i` for iOS Simulator, `a` for Android Emulator, or scan the QR code with the Expo Go app.
155
+
156
+ #### 4. Run Test Suite (116/116 Tests Passing)
157
+ ```bash
158
+ npm test
159
+ ```
160
+
161
+ ### 5. Developer CLI Commands (`agentos`)
162
+ Audit systems, inspect fleets, and run swarms natively in your terminal or CI/CD pipelines:
163
+ ```bash
164
+ # Run 5-point diagnostic health audit across all 7 agents & Spekra bridge
165
+ npx agentos doctor
166
+
167
+ # Inspect live status, authority ceilings, and approvals
168
+ npx agentos fleet status
169
+
170
+ # Execute the 5-stage sequential autonomous swarm pipeline
171
+ npx agentos swarm run
172
+
173
+ # Cryptographically verify SHA-256 block ledger immutability
174
+ npx agentos audit --ledger
175
+ ```
176
+
177
+ ---
178
+
179
+ ## 🔌 REST API Endpoints
180
+
181
+ | Method | Endpoint | Description |
182
+ | :--- | :--- | :--- |
183
+ | `GET` | `/api/status` | Returns live health, uptime, and pending approvals for all agents. |
184
+ | `GET` | `/api/fleet/stream` | Real-time Server-Sent Events (SSE) telemetry stream to Spekra cloud and mobile cockpit. |
185
+ | `GET` | `/api/spekra/status` | Returns Spekra.in connectivity state, trace spans, and mirrored audit blocks snapshot. |
186
+ | `GET` | `/api/memory/query?caller={agent}&entity={id}` | Queries privacy-partitioned facts from the cross-agent memory graph. |
187
+ | `POST` | `/api/memory/record` | Ingests a validated semantic fact into the memory graph. |
188
+ | `POST` | `/api/self-heal/test` | Triggers a simulated 429 fault and auto-heals over secondary rails. |
189
+ | `POST` | `/api/verifier/audit` | Audits proposed agent actions for exact math breakdown and tone safety. |
190
+ | `POST` | `/api/cashhound/cycle` | Executes automated dunning and NPV debt recovery batch cycle. |
191
+ | `POST` | `/api/resolvex/resolve` | Auto-resolves customer support cases and processes idempotent refunds. |
192
+ | `POST` | `/api/localroar/inquiry` | Ingests SMS lead, verifies route density, and calculates instant quotes. |
193
+ | `POST` | `/api/pulsemd/encounter` | Scribes doctor-patient encounter, auto-masks PHI, and drafts SOAP note. |
194
+ | `GET` | `/api/omnilife/audit` | Scans subscriptions for dormant fees and checks passport validity. |
195
+ | `POST` | `/api/sentinel/killswitch` | Administrator emergency kill-switch to quarantine agent actions. |
196
+
197
+ ---
198
+
199
+ ## 🛡️ Security & Privacy Architecture
200
+
201
+ - **Zero Untrusted Execution:** Agents evaluate strictly structured schemas; raw string inputs are never passed to execution rails.
202
+ - **Server-Authoritative Tokens:** Client devices generate cryptographically signed nonces verified by `ServerApprovalGateway`.
203
+ - **PHI / PII Sanitization:** SSNs, credit cards, emails, and phone numbers are automatically redacted before entering shared agent memory.
204
+ - **Tamper-Evident Ledger:** Every agent state change is recorded into a linked SHA-256 block ledger with frozen immutability.
205
+
206
+ ---
207
+
208
+ ## 📄 License
209
+ MIT © [Subash Thiruppathy](https://github.com/subash-thiruppathi)